Improve process.

01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md

@@ -2,46 +2,199 @@
 
 General, vendor-neutral background on the memory technologies referenced throughout this repository's workflows and scripts. This is standard semiconductor/automotive engineering knowledge, not specific to any single tool or manufacturer.
 
-## EEPROM (Electrically Erasable Programmable Read-Only Memory)
+## Source traceability and evidence scope
 
-- Byte- or word-addressable non-volatile memory; individual bytes can typically be erased/rewritten without erasing an entire block.
-- Common in automotive ECUs for storing configuration, calibration constants, VIN, mileage, and — relevant to this repository's governance model — immobilizer-related data (key counts, synchronization values), which is why EEPROM read/write is a recurring, carefully-gated operation in `04_Workflows/`.
-- **Blank/erased state:** typically all bits set to `1` (byte value `0xFF`), though this varies by part family — always confirm from the specific part's datasheet rather than assuming.
-- **Write endurance:** finite number of erase/write cycles per cell (commonly on the order of 10^4–10^6 depending on part generation). This is why the repository's workflows emphasize minimizing unnecessary write operations and always working from a validated copy rather than iterating live writes against the original.
-- **Page/block size:** many EEPROMs write in small pages; partial-page writes may still consume a full write cycle for the page depending on part behavior.
+The repository continues to distinguish between:
 
-## Flash memory
+- PRIMARY-MULTIPROG: directly supported by Multi-PROG documentation or verified Multi-PROG software behavior.
+- PRIMARY-MANUFACTURER: authoritative manufacturer datasheet/manual.
+- SECONDARY-CASE-STUDY: a case study from a third-party researcher, treated as evidence for method design, not as Multi-PROG procedure.
+- REPOSITORY-OBSERVATION: a fact supported by the repository's own existing documentation and traceable source records.
+- UNVERIFIED: not established by the supplied manuals or authoritative references.
 
-- Block/sector-erasable non-volatile memory; unlike EEPROM, a sector generally must be erased (set to blank state) as a whole unit before any byte within it can be rewritten.
-- Used for MCU program memory (firmware) and, in many modern automotive MCUs, for emulated EEPROM (see below) since dedicated EEPROM cells are less common in newer parts.
-- **Sector/block boundaries** matter for scripting: a write that only touches part of a sector may still require erasing (and therefore re-writing) the whole sector's other contents, unless the tool/host manages this transparently.
-- **Program/erase cycling** endurance is generally lower than EEPROM (though write speed is often faster), reinforcing the same "validate before writing" discipline already codified in `04_Workflows/AUTHORIZED_REPAIR_WORKFLOW.md`.
+The Ducati material is handled as SECONDARY-CASE-STUDY material only. It is not promoted to a Multi-PROG procedure.
 
-## Automotive MCU memory maps (general pattern)
+## Terminology normalization
 
-Most automotive MCUs (Bosch, Continental/VDO, Denso, Hitachi/Renesas, Delphi, and others across ECU/TCU/immobilizer/BCM modules) combine several memory regions in one addressable space:
+This repository uses "EEPROM" for electrically erasable memory where that is the intended memory type. Where a memory region is embedded in a microcontroller and documented as an MCU data region, it is labeled as internal EEPROM or data flash / D-FLASH only when the source explicitly identifies that naming. The terminology below is used to avoid conflating different access paths and memory technologies.
 
-| Region | Typical contents |
-| --- | --- |
-| Boot/bootloader area | Low-level code that manages flashing/programming mode; often protected or separately locked |
-| Program flash | Main application firmware |
-| Calibration/data flash or emulated EEPROM | Calibration tables, configuration, VIN, immobilizer data |
-| RAM (volatile) | Runtime state only — not relevant to offline dump analysis |
-| Option/configuration bytes or fuses | Device-level lock/protection bits, sometimes one-time-programmable |
+| Term | Normalized use | Notes |
+| --- | --- | --- |
+| EPROM | Historical or legacy term | Preserve the exact source wording when quoting old material. Do not use as a general replacement for EEPROM in current workflow text. |
+| EEPROM | Electrically erasable memory | Use this for external chip EEPROM and MCU data EEPROM only when the source clearly labels it as EEPROM. |
+| External EEPROM | Separate EEPROM device | Distinct from internal MCU memory; requires separate chip identification and adapter path. |
+| Internal EEPROM | EEPROM embedded in the MCU | Not an external EEPROM chip; avoid treating it as a separate board-level component. |
+| D-FLASH | MCU data flash region | Use only when a source explicitly names D-FLASH or a compatible manufacturer term. |
+| Program FLASH | MCU program memory | Distinct from EEPROM and data flash; typically firmware image storage. |
+| Data FLASH | MCU non-volatile data region | Use for a data region that is flash-backed rather than a dedicated EEPROM cell array. |
+| P-FLASH | Program flash region | Use when the source or manufacturer's naming uses P-FLASH. |
+| Logical address space | Address range as seen by the MCU core | Not necessarily equal to the full physical or paged global memory image. |
+| Global address space | Fully reconstructed physical memory view | Formed from multiple pages or mapped regions. |
+| Banked or paged memory | FLASH arranged in pages/windows | Requires page-register understanding and reconstruction. |
+| Fixed memory window | Common logical window | A selected address range that maps to a banked page. |
+| PPAGE window | Page-select window for paged MCU memory | The page register selects which bank appears in the logical window. |
+| Configuration memory | Protected or option memory region | May be unreadable or restricted for some parts. |
+| Security/configuration area | Protected content | Must be preserved and treated separately from user data. |
+| Raw binary image | Direct acquisition output | Preserve exactly as read; do not overwrite. |
+| Address-bearing image | S-record, HEX, or other addressed format | Carries addresses and therefore supports reconstruction. |
+| Motorola S-record | SREC/S19 record format | Address-bearing, includes record checksums. |
+| S19 file | Motorola S-record variant | Use when the file naming or source uses S19/SREC terminology. |
+| BIN file | Flat binary image | No inherent address metadata; address mapping must be reconstructed separately. |
+| HEX file | Addressed or flat hexadecimal output | Verify whether the format is address-bearing before treating it as a reconstructed memory image. |
 
-Exact offsets and region sizes are **part- and firmware-version-specific** — this repository does not claim to document real offsets for any specific ECU/MCU part number in its public-facing folders; where real offsets are permitted for private authorized use, they belong in the governance-boundaried `07_Authorized_Key_Immobilizer_Work/` scope per that folder's README, not in general Knowledge Base articles.
+## Access-path model
 
-## Why "bench reading" and "boot reading" are different operations
+This repository distinguishes acquisition paths so that a CAN observation or software selection is not mistaken for direct MCU memory access.
 
-- **Bench reading** — the module's MCU/EEPROM is accessed directly (e.g. via a socket adapter or in-circuit clip) with the module removed from the vehicle and often without its own firmware running normally. Gives full, low-level access but requires correct adapter/pinout and power handling.
-- **Boot reading** — the MCU is put into a manufacturer-defined bootloader/programming mode (still often in-circuit or on a bench) and read through that bootloader's protocol rather than by direct memory-cell access. Requires the correct boot-mode entry sequence for that MCU family.
+### A. CAN communication analysis
 
-See `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md` for the procedural workflow built on these concepts.
+Purpose:
+- Observe module communication.
+- Determine bus type when authorized.
+- Capture traffic non-destructively.
+- Correlate message changes with known operating states.
+
+Important limitation:
+- Passive CAN capture does not automatically reveal MCU FLASH or EEPROM contents. It records communication traffic, not a memory dump.
+
+Source context: the Ducati case study includes CAN analysis as part of a broader ECU investigation, but the actual direct memory acquisition still used a BDM-based MCU read path. See evidence below.
+
+### B. Module-level bench mode
+
+Purpose:
+- Power a supported module on the bench.
+- Use an explicitly supported vehicle/module function.
+- Follow the exact Multi-PROG software connection diagram.
+- Read documented memory areas through the supported module workflow.
+
+Safety note:
+- Bench mode must be selected only for a verified module and verified access path. This repository does not genericize connector pinouts or voltage values.
+
+### C. Direct MCU debug or programming interface
+
+Examples can include BDM where source-supported.
+
+Purpose:
+- Access the MCU through its documented debug/programming interface.
+- Read logical memory.
+- Read paged or global memory when supported.
+- Read internal EEPROM or D-FLASH when separately exposed.
+- Preserve configuration areas.
+
+Important limitation:
+- BDM is not assumed to be present or enabled on every MCU. This is a device-specific access path, not a universal automotive MCU method.
+
+### D. External EEPROM access
+
+Purpose:
+- Read a separately identified EEPROM.
+- Use the correct chip selection and adapter.
+- Distinguish in-circuit from removed-chip access.
+
+Important limitation:
+- Do not call internal MCU data EEPROM an external EEPROM. The access path and physical device identification must remain distinct.
+
+### E. File and memory reconstruction
+
+Purpose:
+- Preserve raw output files.
+- Parse address-bearing formats.
+- Derive normalized binary images.
+- Track transformations.
+- Validate reconstructed memory.
+
+Important limitation:
+- CAN analysis and direct MCU memory acquisition are related investigative activities but are not interchangeable access methods.
+
+## Ducati Monster 696 S12X acquisition case study
+
+### Title: Ducati Monster 696 S12X Acquisition Case Study
+
+This section is CASE-STUDY-SPECIFIC and must not be treated as an official Xhorse Multi-PROG procedure.
+
+The following observations are drawn from the Pulse Security Ducati research and are recorded here as a method reference only. They are not a generic S12X or Multi-PROG recipe.
+
+Source references used in this section:
+- Practical CANBUS Reversing – Understanding the Ducati Monster (Pulse Security)
+- Practical Vehicle Reverse Engineering – Ducati ECU Part II (Pulse Security)
+- Adventures with the Ducati CAN bus (Pulse Security)
+- Kvaser CAN Data Frame Messages (Kvaser)
+- USBDM documentation (USBDM)
+- Motorola S-record conversion/reference implementation (arkku/srec)
+
+### Case-study facts recorded with source traceability
+
+1. The factory Siemens ECU contains an S12X-family microcontroller. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II, identification of the Siemens ECU and the MCU family.
+2. The source identifies S12X as part of the 68HC12/HCS12 family. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II, general MCU family discussion.
+3. The direct memory acquisition used the MCU's BDM interface. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article describes direct access via the MCU debug/programming interface.
+4. The source used USBDM, not Multi-PROG. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article explicitly documents USBDM usage.
+5. The first acquisition covered the logical memory range. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article distinguishes logical-space read and full reconstruction.
+6. The result was stored in Motorola S-record format. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II and the srec conversion/reference implementation used for the resulting S-record payloads.
+7. The investigation identified a paged FLASH architecture. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article documents the paged memory model for the MCU family.
+8. The PPAGE register controls which FLASH bank appears in a logical window. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article explains the PPAGE-based memory window mapping.
+9. The researcher compared fixed logical memory with reconstructed global pages to validate the mapping. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the validation process compares logical and global reconstructions.
+10. Hash comparison was used to confirm that reconstructed sections matched corresponding logical-memory sections. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article records hash checks used during validation.
+11. The complete analysis image was assembled from multiple memory regions rather than assuming that one logical-space read represented all FLASH. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; combined region reconstruction is a central methodology.
+12. The final image was loaded into an HCS12-capable reverse-engineering environment. SOURCE: Practical Vehicle Reverse Engineering – Ducati ECU Part II; the article describes loading the reconstructed image for analysis.
+
+### CASE-STUDY-SPECIFIC constraints
+
+- This material is OBSERVED WITH USBDM, not MULTI-PROG PROCEDURE.
+- Do not treat any Ducati case-study addresses, page values, PPAGE values, security bytes, memory maps, or part IDs as generic constants.
+- Any exact values must remain in a device-specific evidence block and require manufacturer datasheet confirmation before reuse.
+- The presence of a paged architecture is a general engineering observation from the case study, not proof that every S12X-based module or every HCS12 ECU follows the same layout.
+
+### Example evidence block without generic reuse
+
+- Device: Siemens Ducati factory ECU, S12X-family MCU
+- Access method: BDM via USBDM
+- Data format: Motorola S-record (S19/SREC)
+- Memory model: paged FLASH with PPAGE-based windowing
+- Validation: logical-space compare + hash comparison + reconstructed global image
+- Scope: CASE-STUDY-SPECIFIC; REQUIRES DEVICE IDENTIFICATION AND DATASHEET CONFIRMATION BEFORE REUSE
+
+## S-record and binary conversion guidance
+
+Motorola S-record files are address-bearing and contain record checksums. They therefore preserve at least the start address, data addresses, and record-level integrity information. A flat BIN file does not inherently preserve source addresses. Converting an S-record file to a BIN requires an explicit mapping policy and validation step.
+
+Required validation for SREC-to-BIN conversion:
+- Validate S-record checksums before conversion.
+- Identify the lowest and highest data addresses.
+- Identify discontinuities and sparse gaps.
+- Record the address offsets and fill byte used.
+- Preserve unimplemented gaps intentionally instead of silently padding to a large size.
+- Compare extracted fixed ranges against the original addressed records.
+- Hash the raw and converted outputs.
+- Never delete the source S19/SREC file after conversion.
+- Record the tool and version used in the conversion pipeline.
+
+This repository's script and validation tooling may reference srec2bin or equivalent conversion utilities as one possible implementation, but such a utility is not assumed to be mandatory. Any tool integration must be checked for license, tested version/commit, and fixture-based validation against malformed checksums, gaps, overlaps, supported record types, and large sparse ranges.
+
+## Paged FLASH reconstruction guidance
+
+A paged-memory workflow must be vendor-neutral and require the following:
+
+1. Identify the exact MCU derivative.
+2. Obtain the authoritative reference manual or datasheet.
+3. Determine logical and global address spaces.
+4. Identify fixed and paged windows.
+5. Identify the page-selection register.
+6. Determine implemented page values.
+7. Read each page without changing unrelated target state.
+8. Store every page separately.
+9. Name pages with target, register, page value, logical window, and timestamp.
+10. Reconstruct the global image using documented mappings.
+11. Compare overlapping fixed and paged ranges.
+12. Hash the compared sections.
+13. Record missing or unreadable pages.
+14. Preserve the fill-byte policy.
+
+If a module is not explicitly identified as paged, do not assume a logical address-space read covers the full device flash. A single logical 16-bit window is not equivalent to a complete physical memory map.
 
 ## Related documents
 
 - `04_Workflows/EEPROM_READ_WRITE_WORKFLOW.md`
 - `04_Workflows/MCU_READ_WRITE_WORKFLOW.md`
 - `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md`
-- `17_MultiPROG_SDK/docs/EEPROM_API.md`, `17_MultiPROG_SDK/docs/FLASH_API.md`
+- `17_MultiPROG_SDK/docs/MANUAL_API_REFERENCE.md`
 - `03_Script_Starter_Kit/examples/35_flash_sector_map_parser.mjs`

04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md

@@ -1,45 +1,81 @@
 # Bench Reading / Boot Reading Workflow
 
 ## Purpose
-Decide between, and safely execute, bench (direct/in-circuit chip access) reading versus boot-mode (bootloader protocol) reading of a module's MCU/EEPROM, and document the trade-offs. See `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md` for the conceptual distinction.
+Decide between, and safely execute, the correct access path for a module's memory or communication analysis. This workflow separates bus observation, bench mode, direct MCU access, external EEPROM access, and file reconstruction so that no single method is mistaken for another.
 
-## Purpose of choosing correctly
-Using the wrong method for a given MCU family can range from "doesn't work" to "risks damaging the part" (e.g. forcing bench-clip access on a part that expects boot-mode entry sequencing, or vice versa).
+## Evidence and scope rules
+
+- This repository does not claim that any specific module or MCU supports boot mode, BDM, or bench access unless the relevant source supports it.
+- The Ducati S12X material is treated as a SECONDARY-CASE-STUDY example. The source used USBDM for BDM access and is not a Multi-PROG procedure.
+- Do not infer pinouts, voltages, or power sequencing from a similar MCU family without a verified module-specific source.
+
+## Access-path decision model
+
+### A. CAN communication analysis
+- Purpose: observe bus traffic, determine module communication mode, correlate state changes, and document traffic non-destructively.
+- Limit: passive CAN capture does not provide the MCU's memory image or EEPROM contents.
+- Use when: the goal is communication analysis, not content extraction.
+
+### B. Module-level bench mode
+- Purpose: power a supported module on the bench and use a supported Multi-PROG workflow for a documented memory region.
+- Limit: the exact supported connection and region must be verified for that module, not assumed from a similar platform.
+- Use when: Multi-PROG explicitly lists the module and memory-domain path as supported.
+
+### C. Direct MCU debug or programming interface
+- Purpose: access the MCU through a documented BDM or equivalent programming/debug interface.
+- Limit: BDM availability is a device-specific property; not every MCU supports it, and not every family uses the same entry conditions.
+- Use when: the manufacturer or a trusted reference describes the interface and the read path is supported by the selected tool.
+
+### D. External EEPROM access
+- Purpose: read a separately identified EEPROM device with the correct adapter and package support.
+- Limit: do not call internal MCU data EEPROM an external EEPROM. These are different physical access paths.
+- Use when: the target is an external EEPROM device distinct from the MCU.
+
+### E. File and memory reconstruction
+- Purpose: preserve raw data, map address-bearing formats, reconstruct normalized images, and validate them.
+- Limit: file reconstruction is a separate step from acquisition; it does not replace a read.
 
 ## Prerequisites
-- Confirmed MCU/EEPROM part number and, ideally, known guidance (from the tool/adapter vendor's supported-device list) on which method that exact part supports.
-- For boot reading: confirmed boot-mode entry sequence for that MCU family from the adapter/tool vendor's documentation.
-- For bench reading: confirmed clip/socket compatibility with the part's package and pinout.
+- Exact module type, manufacturer, and hardware revision identified.
+- Exact MCU or EEPROM part number and package identified from the module or manufacturer reference.
+- A documented supported access path for that exact module and revision.
+- Current-limited bench power, correct adapter, and proven continuity before applying target power.
 
-## Required adapters
-- Bench reading: chip-specific clip/socket adapter.
-- Boot reading: cable/harness matching the module's connector plus whatever boot-mode entry hardware (e.g. specific resistor/jumper condition, or a tool-provided boot adapter) the MCU family requires.
-
-## Wiring references
-- Use the adapter/tool vendor's documented pinout and boot-entry sequence for the exact part; do not improvise from a similar-looking part in the same family, since boot-entry conditions are often part-specific.
+## Required adapters and references
+- Bench reading: a chip-specific clip/socket adapter or documented bench harness that matches the module and target memory device exactly.
+- Boot or debug reading: documented tool/software path, debug adapter, or boot-mode sequence supported for that exact MCU family.
+- Use the adapter/tool vendor's own documentation for exact pinouts, entry conditions, and supported functions. This repository does not maintain generic pin mappings.
 
 ## Safety notes
-- Bench (chip-off or clip) reading risks physical damage to the part/board from clip pressure or accidental short; boot reading avoids desoldering but depends on getting the entry sequence exactly right, and an incorrect sequence can sometimes leave the MCU in an unexpected state.
-- Always attempt the least invasive method first if the adapter/tool documentation confirms it's supported for the exact part.
-- Use current-limited bench power throughout.
+- Always prefer the least invasive supported method that is explicitly proven for the exact module.
+- Use current-limited bench power throughout first-power checks.
+- Treat bench reads and debug reads as separate access paths with different risk profiles.
+- Do not proceed from visual similarity alone.
 
 ## Procedure
-1. **Identify** — confirm exact part number and check adapter/tool vendor documentation for supported access method(s) for that part.
-2. **Choose method** — prefer boot-mode reading if supported and non-invasive; use bench/clip reading if boot mode is unsupported or unreliable for that part.
-3. **Acquisition** — two independent reads regardless of method, byte-for-byte compared and hashed (per baseline workflow).
-4. **Validation** — confirm expected buffer size/signatures for that part before treating the read as usable.
+1. **Identify the target** — record module type, part number, revision, and any known software or hardware identifier.
+2. **Determine the supported path** — choose among CAN observation, module bench mode, direct MCU debug, external EEPROM, or unsupported.
+3. **Document evidence** — store the software selection, module photos, connector/wiring notes, datasheet, and any adapter documentation.
+4. **Prepare the bench** — verify supply polarity, ground reference, continuity, adapter fit, and ESD control.
+5. **Read first** — perform the first read without erase or write unless a verified destructive step is explicitly required.
+6. **Validate the read** — compare independent reads, file size, and hash, and record warnings or incomplete memory ranges.
+7. **Check completeness** — confirm whether the read covered only a logical window, a paged memory region, or the complete addressed image.
+8. **Preserve raw data** — save the raw file and any reconstructed output separately; do not overwrite the original acquisition.
 
 ## Common failures
-- Boot-mode entry sequence slightly wrong (timing, pin state) resulting in a read that returns unexpected data (e.g. all zeros/all `0xFF`) rather than an explicit error.
-- Clip misalignment on bench reads producing an inconsistent second read (caught by the dual-read comparison).
-- Attempting boot mode on a part/revision that does not support it for that specific tool/adapter.
+- Assuming CAN traffic capture is equivalent to a memory dump.
+- Using a similar MCU family to guess the access path.
+- Reusing unverified pinouts or adapter assumptions.
+- Treating a logical window read as a complete flash image without page or mapping validation.
+- Writing or erasing before a stable and validated read is complete.
 
 ## Recovery procedures
-- If a read attempt returns clearly invalid data (wrong size, uniform blank pattern where real data is expected), do not proceed to any write step — re-seat the adapter/re-check the boot sequence and re-read before continuing.
-- If repeated attempts fail, treat this as an adapter/method mismatch rather than a hardware fault until an alternate, tool-vendor-confirmed method has also been tried.
+- If a read fails or is inconsistent, do not proceed to write or erase.
+- Re-seat the adapter, confirm the selected target, and repeat the read using the same documented method.
+- If the access path does not match the module specifically, stop and re-evaluate rather than forcing a similar connection.
 
 ## Related documents
 - `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md`
 - `04_Workflows/EEPROM_READ_WRITE_WORKFLOW.md`
 - `04_Workflows/MCU_READ_WRITE_WORKFLOW.md`
-- `07_Authorized_Key_Immobilizer_Work/GODIAG_XHORSE_HARDWARE_REFERENCE.md` — example bench-adapter hardware (e.g. GT100 breakout box, module-specific test platforms)
+- `07_Authorized_Key_Immobilizer_Work/GODIAG_XHORSE_HARDWARE_REFERENCE.md`

04_Workflows/EEPROM_READ_WRITE_WORKFLOW.md

@@ -1,46 +1,66 @@
 # EEPROM Read/Write Workflow
 
 ## Purpose
-Safely read and, where authorized, write EEPROM contents on an automotive module (ECU/BCM/immobilizer/instrument cluster) while preserving recoverability at every step.
+Safely read and, where authorized, write EEPROM contents on an automotive module while preserving recoverability at every step. This workflow distinguishes external EEPROM devices from internal MCU EEPROM or data-flash areas so that the target memory type is identified before any read or write is attempted.
+
+## Terminology guardrails
+
+- Use "EEPROM" for the electrically erasable memory type when the source indicates that is the intended memory.
+- Do not call internal MCU data EEPROM an external EEPROM.
+- If a source says "internal EEPROM" or "data flash" within a microcontroller, preserve that label instead of flattening it to a generic external EEPROM term.
+- EPROM is a legacy/older term and must not be silently substituted for EEPROM in workflow language.
+
+## Access-path distinction
+
+### External EEPROM access
+- Physical EEPROM chip or package separate from the MCU.
+- Requires separate chip identification, package/adapter matching, and documented device selection.
+
+### Internal MCU EEPROM / D-FLASH / data region
+- Embedded inside the MCU.
+- May be logically exposed as a data region, data flash, D-FLASH, or configuration segment depending on the platform.
+- Requires a verified MCU access path; it is not automatically the same as a separate EEPROM chip.
 
 ## Prerequisites
-- Confirmed authorization for the specific vehicle/module (see `07_Authorized_Key_Immobilizer_Work/README.md` if immobilizer-relevant data is involved).
-- Exact EEPROM part number and package (identified visually or via schematic/service reference) — memory size and pinout vary by part family.
-- Spare, known-good bench power supply with current limiting.
-- Multi-PROG (or equivalent) with a device/adapter entry matching the exact part; confirm the "supported" indicator (see `01_Knowledge_Base/README.md` → "Checksum strategy") rather than assuming compatibility from a similar part number.
+- Confirmed authorization for the specific vehicle/module.
+- Exact EEPROM part number and package identified.
+- Correct adapter or clip for that package.
+- Current-limited bench power and module grounding confirmed before connection.
+- Documented target selection for the exact device or region, not a similar part number.
 
-## Required adapters
-- In-circuit clip or socket adapter matching the EEPROM package (e.g. SOIC8, TSSOP8, DIP8 — package varies by part).
-- If desoldering is required: appropriate rework station and ESD protection; note desoldering as a higher-risk path with its own recovery burden if the part is damaged.
-
-## Wiring references
-- Use the adapter/tool manufacturer's official pinout documentation for the specific clip/socket model in use; this repository does not maintain a general pinout table since it is adapter- and part-specific and changes across hardware revisions.
-- Confirm orientation (pin 1 marking) before applying power — reversed orientation is a common cause of part damage.
+## Required adapters and references
+- In-circuit clip or socket adapter matching the EEPROM package exactly.
+- Manufacturer or adapter documentation for the part, package, and supported access path.
+- If desoldering is required, document the package handling and recovery plan.
 
 ## Safety notes
 - Never power the EEPROM in-circuit and out-of-circuit simultaneously.
-- Use current-limited bench supply on first power-up of any in-circuit read to catch a short before it damages the part.
-- Keep the module's original harness connections photographed/documented before disconnecting (per `04_Workflows/AUTHORIZED_REPAIR_WORKFLOW.md` intake step).
+- Use current-limited bench supply on first power-up.
+- Do not assume that a device is compatible because it shares a similar package or family name.
+- If the module contains security-related data, follow the governance boundaries defined in the repository's authorized-workflow scope.
 
-## Procedure (maps onto the baseline workflow)
-1. **Intake** — record authorization, module identity, exact EEPROM part number.
-2. **Acquisition** — two independent reads, byte-for-byte compared, SHA-256 recorded (see `03_Script_Starter_Kit/examples/02_double_read_verifier.mjs`).
-3. **Development** — work on a copy; maintain an explicit allow-list of writable offsets (see `03_Script_Starter_Kit/examples/04_allowlisted_patch_demo.mjs`).
-4. **Validation** — verify size, blank regions outside the allow-list are untouched, and checksum where applicable.
-5. **Release** — write only after validation passes; save the original read under a preserved filename before writing anything back.
+## Procedure
+1. **Intake** — record authorization, module identity, part number, package, and whether the target is external EEPROM or internal MCU data storage.
+2. **Evidence** — collect the adapter documentation, wiring evidence, and the device selection list or software screenshot.
+3. **Read first** — perform two independent reads where practical and compare them before any write decision.
+4. **Validation** — confirm file size, blank regions, and hash stability; treat any mismatch as data-quality failure.
+5. **Development** — work on a copy and keep an explicit allow-list if writes are being prepared.
+6. **Release** — write only after the read is stable and valid; save the original read and backup images before any destructive operation.
 
 ## Common failures
-- Wrong part/package selected in the tool's device list, producing a read that is the wrong size or all-blank/all-`0xFF`.
-- Clip misalignment causing an intermittent read that differs between the two required reads (this is exactly what the dual-read check is designed to catch — do not proceed if reads differ).
-- Write interrupted mid-cycle (power loss, clip slip) leaving the part in a partially-written, inconsistent state.
+- Wrong part or package selected in the device list.
+- Clip misalignment or partial connection causing inconsistent reads.
+- Confusing internal MCU data memory with external EEPROM storage.
+- Writing from a corrupted or partially validated work image.
 
 ## Recovery procedures
-- If a write is interrupted or verification fails: do not attempt another write from the same (possibly corrupted) working copy. Re-read the module first to establish its actual current state, then restore from the last known-good backup.
-- Always keep the original pre-write backup and at least one prior known-good backup, named with case ID/module/region/date, per `04_Workflows/AUTHORIZED_REPAIR_WORKFLOW.md` → "Release".
-- If the part appears bricked (reads as all-blank/garbage after a failed write and does not respond normally), the module is a candidate for the same "bench reading" recovery path documented in `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md`, or physical EEPROM replacement/reprogramming with a known-good backup.
+- If a write is interrupted or verification fails, re-read the target before attempting another write.
+- Keep the original pre-write backup and a known-good backup file distinct from any working copy.
+- If the part appears bricked or the data is inconsistent after a failed write, treat it as a hardware/connection or method mismatch and re-check the access path before any further destructive action.
 
 ## Related documents
 - `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md`
+- `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md`
+- `04_Workflows/MCU_READ_WRITE_WORKFLOW.md`
 - `17_MultiPROG_SDK/docs/EEPROM_API.md`
 - `17_MultiPROG_SDK/templates/template_eeprom.mjs`
-- `07_Authorized_Key_Immobilizer_Work/GODIAG_XHORSE_HARDWARE_REFERENCE.md` — example bench-adapter hardware

04_Workflows/MCU_READ_WRITE_WORKFLOW.md

@@ -1,45 +1,217 @@
 # MCU Read/Write Workflow
 
 ## Purpose
-Read and, where authorized, write the combined program-flash/data (EEPROM-emulated) memory of an automotive MCU — distinct from a standalone EEPROM chip because most of the address space is program flash with its own erase/program discipline (see `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md`).
+This workflow is a read-first methodology for automotive MCU memory acquisition and reconstruction. It defines how to document the target, choose the correct access path, read the memory without destructive actions, validate repeated acquisitions, and preserve raw and derived outputs before any write or erase path is considered.
 
-## Prerequisites
-- Confirmed authorization for the specific vehicle/module.
-- Exact MCU part number and package identified (silicon markings can be sanded/relabeled on some counterfeit or reworked boards — cross-check against known-good reference photos for that platform where possible).
-- Understanding of whether this MCU family requires bench (direct pin) access, boot-mode access, or supports in-circuit reading through a bootloader — see `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md` for how to decide.
+## Read-first principles
 
-## Required adapters
-- MCU-family-specific adapter/socket (BGA/QFP adapters differ significantly by package and pitch).
-- A programmer/tool profile that explicitly lists the exact MCU part — do not assume a "similar" part number behaves identically; flash geometry (sector size/count) varies even within a family.
+- Do not perform erase, blank check, or write as part of the normal read workflow unless an explicitly verified procedure requires it.
+- Distinguish between a supported module-level Multi-PROG path, a direct debug interface, and a different external-memory access path.
+- Treat a logical memory window as a subset of the total device image unless the source explicitly proves it is the complete mapping.
+- Preserve the original acquisition and any reconstructed outputs separately; never overwrite the raw read.
 
-## Wiring references
-- Follow the adapter manufacturer's documented pinout for the specific MCU package; do not improvise pin mapping from a different package variant of the "same" chip.
-- Confirm boot-mode entry pins (if boot reading) match the documented sequence for that exact MCU family before applying power.
+## Stage 1: Authorization and module identification
 
-## Safety notes
-- MCU packages are more prone to adapter-pressure damage (BGA pads, fine-pitch QFP) than simple 8-pin EEPROMs — inspect solder/pad condition before and after.
-- Program flash erase/write endurance is typically lower than EEPROM; avoid repeated write cycles during development — validate against a copy before committing to hardware.
-- If the module has an immobilizer-relevant data region within the same MCU (common on modern combined ECUs), treat that region under `07_Authorized_Key_Immobilizer_Work/README.md` governance even though the rest of the read is general firmware.
+Record the following before any acquisition attempt:
+- Module type
+- Manufacturer
+- Part number
+- Hardware number
+- Software number
+- PCB revision
+- Vehicle application
+- MCU top marking
+- External EEPROM marking
+- Module ownership or authorization
+- Source photographs
+- Existing Multi-PROG selection, if present
 
-## Procedure
-1. **Intake** — record authorization, exact MCU part number/package, and which regions (program flash vs. data/EEPROM-emulated) are in scope.
-2. **Acquisition** — two independent full reads, byte-for-byte compared and hashed, per the baseline workflow.
-3. **Development** — segment the buffer logically (program flash region vs. data region) before editing anything; treat program flash edits as higher risk than data-region edits.
-4. **Validation** — verify checksum/CRC the firmware itself checks at boot (if known for that platform) in addition to the generic allow-list diff check.
-5. **Release** — write only after validation; preserve rollback image.
+Important:
+- Do not proceed from a visual resemblance alone.
+- If the exact device cannot be identified, the task remains unverified and should not advance to a write or erase step.
 
-## Common failures
-- Confusing flash sector boundaries and only erasing/rewriting part of a sector, corrupting adjacent data that wasn't intended to change.
-- Firmware checksum not recalculated after a manual patch, causing the MCU to refuse to boot or run in a degraded/limp mode.
-- Wrong MCU variant selected (same die, different flash size) truncating or misreading the image.
+## Stage 2: Evidence collection
 
-## Recovery procedures
-- Keep the original full read as the baseline recovery image regardless of how far development/validation proceeds.
-- If a write leaves the MCU unresponsive, attempt boot-mode recovery (see `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md`) before considering the module unrecoverable.
-- If checksum validation fails post-write, do not attempt to "patch around" it live — restore from backup and re-diagnose offline against a copy.
+Collect and store:
+- Multi-PROG software selection screenshots
+- Multi-PROG wiring diagram
+- Multi-PROG memory-region list
+- Manufacturer datasheet
+- Package information
+- Debug-interface documentation
+- Trusted module-specific wiring evidence
+- Existing repository references
+
+Record the date and the tool software version.
+
+## Stage 3: Access-path decision
+
+Determine whether the supported path is one of the following:
+- Vehicle/module bench mode
+- Direct MCU BDM
+- Direct MCU boot mode
+- External EEPROM
+- CAN observation only
+- Unsupported or unknown
+
+Never select a path solely because a related MCU family uses that path.
+
+## Stage 4: Bench preparation
+
+Create a checklist containing:
+- Current-limited regulated supply
+- Correct ground reference
+- Polarity verification
+- Connection continuity check
+- Short-circuit check
+- Correct adapter selection
+- Correct target-voltage selection
+- Correct software target
+- Stable contact
+- ESD controls
+- Original-state photographs
+- Read-only plan
+- Recovery plan
+- Automatic-write or automatic-erase warning review
+
+Do not add fixed voltage or current values unless the module-specific source verifies them.
+
+## Stage 5: First acquisition
+
+The first operation must be read-only whenever supported.
+
+Record:
+- Tool
+- Tool software version
+- Selected device
+- Adapter
+- Connection method
+- Named memory region
+- Reported start address
+- Reported length
+- Output format
+- Read duration
+- Warnings
+- Tool log
+- Resulting filename
+
+Do not perform erase, blank check, or write as part of the normal read workflow unless explicitly required and verified.
+
+## Stage 6: Repeated-read validation
+
+Require at least two independent reads where practical.
+
+Compare:
+- File size
+- Cryptographic hash
+- Byte-for-byte equality
+- Blank regions
+- Entropy distribution
+- Repeating sections
+- Vector locations where source-supported
+- Expected identifiers
+- Address coverage
+
+Classify the result:
+- IDENTICAL REPEATED READS
+- STABLE WITH DOCUMENTED VOLATILE DIFFERENCES
+- INCONSISTENT
+- TRUNCATED
+- ADDRESS-MAPPING UNKNOWN
+- REQUIRES ADDITIONAL VALIDATION
+
+Never call one successful read "verified."
+
+## Stage 7: Memory-region completeness
+
+Check whether the acquisition includes:
+- Fixed logical range only
+- Paged FLASH
+- Internal EEPROM
+- D-FLASH
+- RAM
+- Configuration area
+- Security area
+- Unimplemented ranges
+
+Do not assume that a logical 16-bit address-space read includes all physical FLASH.
+
+For paged architectures, require:
+- Verified MCU derivative
+- Manufacturer memory map
+- Page-register definition
+- Implemented page ranges
+- Fixed-window relationship
+- Proof of reconstruction
+- Overlap comparison
+
+## Stage 8: Preserve raw and derived files
+
+Never overwrite the raw acquisition.
+
+Use a structure compatible with the repository, representing:
+- raw/
+- normalized/
+- reconstructed/
+- validation/
+- metadata/
+- logs/
+
+If equivalent existing directories already exist, use them instead.
+
+For every transformation, store:
+- Input hash
+- Output hash
+- Tool
+- Tool version
+- Exact command or method
+- Address offset
+- Fill byte
+- Output length
+- Timestamp
+- Operator notes
+
+## Supporting guidance: paged FLASH reconstruction
+
+1. Identify the exact MCU derivative.
+2. Obtain the authoritative reference manual or datasheet.
+3. Determine logical and global address spaces.
+4. Identify fixed and paged windows.
+5. Identify the page-selection register.
+6. Determine implemented page values.
+7. Read each page without changing unrelated target state.
+8. Store every page separately.
+9. Name pages with target, register, page value, logical window, and timestamp.
+10. Reconstruct the global image using documented mappings.
+11. Compare overlapping fixed and paged ranges.
+12. Hash compared sections.
+13. Record missing or unreadable pages.
+14. Preserve fill-byte policy.
+
+## Supporting guidance: S-record and binary conversion
+
+Motorola S-record is address-bearing and includes record checksums. A flat BIN does not inherently preserve source addresses. Any S-record-to-BIN conversion must therefore validate the source data, identify address ranges, record offsets, and preserve unimplemented gaps.
+
+Required validation steps:
+- Validate S-record checksums.
+- Identify the lowest and highest data addresses.
+- Identify discontinuities.
+- Record address offsets.
+- Record the selected fill byte.
+- Preserve unimplemented gaps intentionally.
+- Avoid accidental multi-megabyte or gigabyte padding.
+- Compare extracted fixed ranges against the original addressed records.
+- Hash raw and converted outputs.
+- Never delete the source S19/SREC file after conversion.
+
+The repository may document a utility such as srec2bin as one possible converter, but it must not be treated as mandatory if a validated converter already exists and the project has a preferred toolchain.
+
+## Ducati case-study note
+
+The Ducati Monster 696 material is relevant as a case study for method design, not as a generic Multi-PROG procedure. The case study demonstrates a direct BDM read with USBDM, a paged FLASH architecture, ppage-based windowing, S-record output, and hash-based validation. Those observations must be labeled CASE-STUDY-SPECIFIC and must not be reused as generic constants without device identification and manufacturer confirmation.
 
 ## Related documents
 - `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md`
 - `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md`
-- `17_MultiPROG_SDK/docs/FLASH_API.md`, `17_MultiPROG_SDK/docs/EEPROM_API.md`
-- `03_Script_Starter_Kit/examples/35_flash_sector_map_parser.mjs`
+- `04_Workflows/EEPROM_READ_WRITE_WORKFLOW.md`
+- `17_MultiPROG_SDK/docs/MANUAL_API_REFERENCE.md`

04_Workflows/README.md

@@ -14,6 +14,18 @@ All workflows in this folder follow the same validation/release discipline estab
 | Immobilizer Backup / Restore | [IMMOBILIZER_BACKUP_RESTORE_WORKFLOW.md](IMMOBILIZER_BACKUP_RESTORE_WORKFLOW.md) |
 | Authorized Key Learning | [AUTHORIZED_KEY_LEARNING_WORKFLOW.md](AUTHORIZED_KEY_LEARNING_WORKFLOW.md) |
 
+## Scope and evidence note
+
+These workflows separate the following acquisition paths clearly:
+
+- CAN communication analysis
+- Module-level bench mode
+- Direct MCU debug or programming interface
+- External EEPROM access
+- File and memory reconstruction
+
+The repository's memory concepts page captures the terminology normalization and includes the Ducati Monster 696 S12X case study as CASE-STUDY-SPECIFIC material. That case study is not a generic Multi-PROG workflow and is not to be treated as an official procedure for all S12X families.
+
 ## Scope note
 
 These workflows are procedural and adapter-agnostic. They describe *what to verify and record*, not exact security algorithms, real memory offsets, or bypass techniques — that boundary is intentional (see `CONTRIBUTING.md` and `07_Authorized_Key_Immobilizer_Work/README.md`). Real, platform-specific security data belongs only in the governance-boundaried `07_Authorized_Key_Immobilizer_Work/` scope, never in this general-purpose folder.

17_MultiPROG_SDK/tests/template_catalog.test.mjs

@@ -2,8 +2,12 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readdirSync, readFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-const templateDir = path.resolve("17_MultiPROG_SDK/templates");
+const templateDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../templates",
+);
 const templates = readdirSync(templateDir)
   .filter((name) => name.endsWith(".mjs"))
   .sort();

17_MultiPROG_SDK/tests/workflow_templates.test.mjs

@@ -2,8 +2,12 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import { readFileSync } from "node:fs";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
-const templateDir = path.resolve("17_MultiPROG_SDK/templates");
+const templateDir = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../templates",
+);
 
 const checksumTemplate = readFileSync(
   path.join(templateDir, "template_checksum_workflow.mjs"),
@@ -41,7 +45,7 @@ test("inventory workflow template contains expected metadata", () => {
 
 test("workflow templates are documented in the SDK structure", () => {
   const readme = readFileSync(
-    path.resolve("17_MultiPROG_SDK/README.md"),
+    path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../README.md"),
     "utf8",
   );
   for (const snippet of expectedSnippets) {

docs/reports/knowledge-consistency-report.md

@@ -32,6 +32,19 @@ The review does not promote a repository statement to fact merely because it is
 
 The repeated API tables in `13_Research_Expansion/MULTIPROG_API_REFERENCE.md`, per-function SDK pages, and the manual-derived reference should not be treated as equally authoritative. The manual-derived reference is the source for supplied-PDF wording; the other pages retain discovery or implementation-status roles.
 
+## Implementation change map
+
+| Source | Source section | Extracted fact | Existing target file | Existing section | Proposed change | Evidence level | Validation status |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Pulse Security Ducati case study | ECU identification and BDM analysis | Factory Siemens ECU contains an S12X-family MCU; direct acquisition used BDM via USBDM | `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md` | Ducati case study | Add a labeled CASE-STUDY-SPECIFIC section with source references and explicit non-Multi-PROG caution | SECONDARY-CASE-STUDY | Confirmed by added case-study section |
+| Pulse Security Ducati case study | Memory reconstruction and PPAGE discussion | S12X uses paged FLASH; PPAGE selects logical window; reconstruction compares logical and global pages | `04_Workflows/MCU_READ_WRITE_WORKFLOW.md` | Paged FLASH reconstruction | Add paged-memory and reconstructed-image validation requirements | SECONDARY-CASE-STUDY | Integrated into workflow guidance |
+| Pulse Security Ducati case study | S-record output | Result stored in Motorola S-record form and validated via hash comparison | `01_Knowledge_Base/AUTOMOTIVE_MEMORY_CONCEPTS.md` | S-record and binary conversion guidance | Document S-record checksums, address-bearing semantics, and conversion validation | SECONDARY-CASE-STUDY | Added to concepts doc |
+| Multi-PROG User Manual / Script Manual | device / memory terminology and supported read/write operations | Memory areas include FLASH, CFLASH, CODE, ROM, DFLASH, EEPROM, DATA, INF, Config | `17_MultiPROG_SDK/docs/MANUAL_API_REFERENCE.md` | Memory-area reference | Preserve as canonical manual terminology and cross-link from workflow docs | PRIMARY-MULTIPROG | Confirmed by manual-derived reference |
+| Multi-PROG User Manual / Script Manual | API docs and scripting | The script host exposes generic read/write operations and manual-documented functions; exact host verification remains pending | `17_MultiPROG_SDK/docs/DEVICE_API.md`, `EEPROM_API.md`, `FLASH_API.md` | API notes | Keep manual documentation and explicitly mark live-host verification as `NOT VERIFIED` | PRIMARY-MULTIPROG | Confirmed by doc review |
+| Repository workflow docs | bench and boot reading | Bench mode and direct debug are distinct access paths | `04_Workflows/BENCH_AND_BOOT_READING_WORKFLOW.md` | Access-path decision model | Separate CAN, bench, MCU, EEPROM, and reconstruction paths | REPOSITORY-OBSERVATION | Updated and cross-linked |
+| Repository workflow docs | EEPROM and MCU generic guidance | Distinguish external EEPROM from internal MCU data memory | `04_Workflows/EEPROM_READ_WRITE_WORKFLOW.md` | Purpose and terminology guardrails | Add explicit terminology normalization and path separation | REPOSITORY-OBSERVATION | Updated |
+| Repository workflow docs | workflow index and terminology | Workflow definitions were too generic and conflated memory types | `04_Workflows/README.md` | index intro | Add access-path and evidence note for the canonical workflow model | REPOSITORY-OBSERVATION | Updated |
+
 ## Duplicate and overlapping content
 
 | Overlap | Finding | Actionable interpretation |