docs(amiga): complete AmigaOS 3.1/3.2 developer reference — 172 files across 17 sections

Comprehensive technical documentation covering:
- Hardware: OCS/ECS/AGA custom chip registers, Copper & Blitter deep dives
- Boot sequence: cold boot through startup-sequence
- Binary format: HUNK executable spec, relocation, debug info
- Linking & ABI: .fd files, LVO tables, register calling conventions
- Exec kernel: tasks, interrupts, memory, signals, semaphores
- AmigaDOS: file I/O, FFS/OFS layout, CLI/Shell scripting
- Graphics: planar bitmaps, Copper programming, HAM/EHB modes
- Intuition: screens, windows, IDCMP, BOOPSI
- Devices: trackdisk, SCSI, serial, timer, audio, keyboard
- Libraries: utility, expansion, IFFParse, locale, ARexx
- Networking: bsdsocket API, SANA-II, TCP/IP stack comparison
- Toolchain: GCC, vasm/vlink, SAS/C, NDK, debugging
- Reverse engineering: IDA/Ghidra setup, compiler fingerprints, case studies
- CPU & MMU: 68040/060 emulation libs, PMMU, cache management
- Driver development: SANA-II, Picasso96/RTG, AHI audio

All files include breadcrumb navigation. No local paths or proprietary content.

04_linking_and_libraries/shared_libraries_runtime.md

@@ -0,0 +1,116 @@
+[← Home](../README.md) · [Linking & Libraries](README.md)
+
+# Shared Library Runtime Mechanics
+
+## Overview
+
+AmigaOS shared libraries are **resident in memory** — once opened, the same code is shared by all tasks. The OS tracks open counts, handles version negotiation, and defers unloading until all users have closed the library.
+
+---
+
+## Library Discovery: `OpenLibrary()`
+
+```c
+struct Library *OpenLibrary(CONST_STRPTR libName, ULONG version);
+```
+
+`exec.library` searches for the library in this order:
+
+1. `exec.library` LibList (already-open libraries in RAM)
+2. Resident module list (ROM-resident: exec, graphics, etc.)
+3. DOS path search — `LIBS:` assign — scan for `libName`
+4. If found on disk: `LoadSeg()` + `InitLib` → add to LibList
+5. Increment `lib_OpenCnt`
+6. Call library's `Open()` vector
+7. Return library base pointer (NULL on failure or version mismatch)
+
+### Version Checking
+
+```c
+DOSBase = (struct DosLibrary *)OpenLibrary("dos.library", 36);
+if (!DOSBase) { /* OS older than 2.0 — handle gracefully */ }
+```
+
+The `version` argument is the **minimum** acceptable `lib_Version`. Version 0 accepts any.
+
+| Library | Version | OS |
+|---|---|---|
+| `exec.library` | 33 | OS 1.2 |
+| `exec.library` | 36 | OS 2.0 |
+| `exec.library` | 39 | OS 3.0 |
+| `exec.library` | 40 | OS 3.1 |
+| `exec.library` | 44 | OS 3.2 |
+
+---
+
+## Library Base Structure
+
+```c
+/* exec/libraries.h */
+struct Library {
+    struct Node lib_Node;     /* ln_Type = NT_LIBRARY */
+    UBYTE       lib_Flags;    /* LIBF_SUMUSED, LIBF_DELEXP */
+    UBYTE       lib_Pad;
+    UWORD       lib_NegSize;  /* bytes of JMP table preceding base */
+    UWORD       lib_PosSize;  /* sizeof(Library) + private fields */
+    UWORD       lib_Version;
+    UWORD       lib_Revision;
+    APTR        lib_IdString; /* "dos.library 40.1 (16.7.93)" */
+    ULONG       lib_Sum;      /* JMP table checksum */
+    UWORD       lib_OpenCnt;  /* reference count */
+};
+```
+
+The pointer returned by `OpenLibrary` points to this structure. The JMP table is **below** the base at negative offsets.
+
+---
+
+## Standard Library Vectors
+
+| Offset | Function | Description |
+|---|---|---|
+| −6 | `Open` | Increment open count, return base |
+| −12 | `Close` | Decrement count, optionally expunge |
+| −18 | `Expunge` | Free library if open count == 0 |
+| −24 | `Reserved` | Always NULL |
+| −30 and below | Library-specific | Per `.fd` file |
+
+---
+
+## Open Count and Expunge Deferral
+
+```c
+/* exec.library CloseLibrary() pseudo-code */
+lib->lib_OpenCnt--;
+if (lib->lib_OpenCnt == 0) {
+    BPTR seg = CallVector(lib, CLOSE_VEC);
+    if (seg) UnLoadSeg(seg);
+}
+```
+
+A library sets `LIBF_DELEXP` when it cannot unload (low memory). On the next close that drops the count to zero, expunge runs.
+
+---
+
+## Open/Close Lifecycle Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Unloaded
+    Unloaded --> Initialised : LoadSeg + InitLib
+    Initialised --> Open : lib_OpenCnt++ (OpenLibrary)
+    Open --> Open : additional opens
+    Open --> Initialised : CloseLibrary, count > 0
+    Initialised --> Expunging : CloseLibrary, count == 0
+    Expunging --> Unloaded : Expunge OK — FreeMem + UnLoadSeg
+    Expunging --> Initialised : LIBF_DELEXP — deferred
+```
+
+---
+
+## References
+
+- NDK39: `exec/libraries.h`, `exec/nodes.h`
+- ADCD 2.1 Autodocs: `OpenLibrary`, `CloseLibrary`, `MakeLibrary`
+- *Amiga ROM Kernel Reference Manual: Libraries* — library creation chapter
+- http://amigadev.elowar.com/read/ADCD_2.1/Libraries_Manual_guide/node0124.html