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.

01_hardware/aga_a1200_a4000/aga_palette.md

@@ -0,0 +1,134 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [AGA](README.md)
+
+# AGA Palette & Colour System
+
+## Overview
+
+AGA provides **256 colour registers** (COLOR00–COLOR255), each **24-bit RGB** (8 bits per channel). This replaces OCS/ECS's 32 registers with 12-bit colour.
+
+## Colour Register Layout
+
+```
+ADDRESS:  $DFF180 + (n × 2)    for register n (0–255)
+```
+
+AGA extends the register space:
+```
+$DFF180–$DFF1BE  COLOR00–COLOR31   (same addresses as OCS/ECS)
+$DFF180–$DFF3BE  COLOR00–COLOR255  (full AGA range — needs BPLCON4 bank select)
+```
+
+The 256 colour registers are accessed in 64-register **banks** selected by `BPLCON4`.
+
+## Writing 24-bit Colours
+
+Each colour register holds 12 bits directly (OCS/ECS compatible). The upper 12 bits (the "low nibble") are written via a second access with `LOCT` set in BPLCON3.
+
+### Manual 24-bit write sequence:
+
+```asm
+; Write color $FF8040 (R=$FF, G=$80, B=$40) to COLOR00
+
+; Step 1: Write high nibble ($F84 = top 4 bits of R,G,B)
+move.w  #$0F84, COLOR00+custom   ; $0RGB high nibble
+
+; Step 2: Set LOCT bit in BPLCON3 to enable low nibble write
+bset    #9, BPLCON3+custom+1     ; bit 9
+
+; Step 3: Write low nibble ($F04 = low 4 bits of R,G,B → $0F, $08, $04 → $F84 again!)
+; Actually: low nibble of FF = F, low nibble of 80 = 0, low nibble of 40 = 0
+move.w  #$0F00, COLOR00+custom   ; low nibble
+
+; Step 4: Clear LOCT
+bclr    #9, BPLCON3+custom+1
+```
+
+### Using LoadRGB32()
+
+The preferred OS call:
+```c
+#include <graphics/view.h>
+#include <proto/graphics.h>
+
+/* Table: count, index, then 0x00RRGGBB values, terminated by ~0 */
+ULONG table[] = {
+    4, 0,             /* 4 colours starting at index 0 */
+    0x00FF0000,       /* COLOR00: red   */
+    0x0000FF00,       /* COLOR01: green */
+    0x000000FF,       /* COLOR02: blue  */
+    0x00FFFFFF,       /* COLOR03: white */
+    ~0UL              /* terminator */
+};
+LoadRGB32(viewport, table);
+```
+
+`LoadRGB32()` (graphics.library LVO -$192) is the AGA-correct way to set colours. It handles the two-write LOCT protocol internally and is available from OS 3.0+.
+
+### Using LoadRGB4() — OCS/ECS compatible (12-bit)
+
+```c
+UWORD colours[32] = { 0x000, 0xF00, 0x0F0, ... };
+LoadRGB4(viewport, colours, 32);  /* sets 32 colours from 12-bit table */
+```
+
+`LoadRGB4()` is safe on all chipsets but only provides 12-bit precision on AGA.
+
+## HAM8 Mode (Hold-And-Modify, 8-bit)
+
+HAM8 is the AGA extension of OCS's HAM6. It uses 8 bitplanes:
+
+- **Bits 7-6** of each pixel: mode select
+  - `00` = index mode (look up COLOR00–COLOR63)
+  - `01` = modify blue channel
+  - `10` = modify red channel
+  - `11` = modify green channel
+- **Bits 5-0**: 6-bit value for the selected channel (or 6-bit colour index)
+
+Result: 2^18 = **262,144 simultaneous colours** from adjacent-pixel modification.
+
+Enabling HAM8:
+```asm
+; BPLCON0: 8 planes (BPU=8, BPU3=1, BPU2-0=000), HAM=1, ECSENA=1
+move.w  #$9811, BPLCON0+custom
+```
+
+## Colour Modes Summary
+
+| Mode | Planes | Colours | Method |
+|---|---|---|---|
+| Standard | 1–8 | 2–256 | Direct palette lookup |
+| EHB | 6 | 64 | Extra Half-Brite (OCS/ECS compat) |
+| HAM6 | 6 | 4096 | Hold-and-modify 4-bit channels |
+| HAM8 | 8 | 262,144 | Hold-and-modify 6-bit channels |
+| Dual Playfield | 3+3 | 8+8 | Two independent 8-colour layers |
+
+## Colour Bank Selection (BPLCON4)
+
+The 256 colour registers are split into 4 banks of 64:
+
+| BPLAM | Bank | Registers |
+|---|---|---|
+| $00 | 0 | COLOR00–COLOR63 |
+| $40 | 1 | COLOR64–COLOR127 |
+| $80 | 2 | COLOR128–COLOR191 |
+| $C0 | 3 | COLOR192–COLOR255 |
+
+Dual playfield can use BPLCON4 to give each playfield a different 64-colour bank.
+
+## OS Colour Management
+
+`graphics.library` manages palette via the `ColorMap` structure attached to a `ViewPort`:
+
+```c
+struct ColorMap *cm = GetColorMap(256);     /* allocate 256-entry AGA map */
+SetRGB32(vp, n, r, g, b);                  /* set one colour (24-bit each) */
+LoadRGB32(vp, table);                       /* bulk load */
+FreeColorMap(cm);
+```
+
+## References
+
+- NDK39: `graphics/view.h` — ColorMap, LoadRGB32
+- ADCD 2.1 Autodocs: graphics — LoadRGB32, SetRGB32
+- http://amigadev.elowar.com/read/ADCD_2.1/Libraries_Manual_guide/node02B4.html
+- AmigaMail Vol. 2 — AGA colour system articles