diff --git a/CLAUDE.md b/CLAUDE.md
index 7796ac1..fd96e07 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -49,7 +49,7 @@ Adding a feature usually means adding a new script command in
 | Phase | Module | Status | Summary |
 |-------|--------|--------|---------|
 | 1 | `bs/` cleanup, REPL polish, README | **done** (commit `7cb3627`) | Fix format-strings, delete dead code, tab-completion, banner |
-| 2 | `fpga/` | **done** (commit `545fe09`) | Per-target descriptor (IDCODE, BSDL, IR codes, proxy path, quirks). Compile-time registry. |
+| 2 | `fpga/` | **done** (commit `545fe09`) | Per-target descriptor (IDCODE, BSDL, IR codes, proxy path, caveats). Compile-time registry. |
 | 2.5 | `bscan_spi/` | **done** (commit `dec0d14`) | Load BSCAN proxy bitstream via `CFG_IN`, expose fast `bscan_spi_xfer()` via `USER1`. Required for realistic flashing speeds. |
 | 3 | `spi_flash/` | **done** (commit `c4afe87`) | Chip DB (JEDEC ID → page/sector/cmd set) + generic `read/erase/program/verify` over an `xfer` callback. detect+read validated on KCU105; erase/program implemented but not yet hardware-tested. |
 | 4 | script commands | in progress | `flash_detect` + `flash_read` done (read-only, validated). `flash_write/erase/verify` pending — destructive on a config flash, test carefully. |
@@ -87,7 +87,7 @@ derived from the BSDL alone:
 - `cfg_in_ir_code`, `user1_ir_code`, `jprogram_ir_code` — Xilinx-specific
   private IR opcodes (read from BSDL when available)
 - `proxy_bitstream_path` — path to the BSCAN proxy `.bit` for this part
-- `quirks` — flags for known caveats (e.g. CCLK via STARTUPE3)
+- `caveats` — flags for known hardware gotchas (e.g. CCLK via STARTUPE3)
 
 Registry is a compile-time array. Adding a part = one entry + its
 `.bsd` in `bsdl_files/` + its proxy `.bit` in `bscan_proxies/`.
diff --git a/doc/tutorial.md b/doc/tutorial.md
index 132f1b8..69e97b9 100644
--- a/doc/tutorial.md
+++ b/doc/tutorial.md
@@ -97,7 +97,7 @@ compile-time registry in `modules/fpga/fpga.c`:
 ```
 bs_explorer> fpga_info
 Device 0  IDCODE 0x04A56093  -> Xilinx Kintex UltraScale+ XCKU15P [Xilinx UltraScale+]
-           quirk: CCLK routed via STARTUP primitive (not drivable in EXTEST)
+           caveat: CCLK routed via STARTUP primitive (not drivable in EXTEST)
 ```
 
 If you get `not in registry`, add an entry — see
@@ -146,7 +146,7 @@ Pin names depend on the board: dump `jtag_pins 0` to discover
 them. On Xilinx FPGAs, the SPI flash is typically wired to the
 configuration bank (e.g. `D00_MOSI_0`, `D01_DIN_0`, `FCS_B_0`) —
 **except** `CCLK`, which goes through the `STARTUPE3` primitive and is
-not drivable in EXTEST (the `CCLK_VIA_STARTUP` quirk on the target).
+not drivable in EXTEST (the `CCLK_VIA_STARTUP` caveat on the target).
 
 Send the JEDEC ID command (`0x9F` + 3 dummy bytes):
 
@@ -183,8 +183,8 @@ For an FPGA that's not in the registry yet:
 
 3. **Add an entry** to `fpga_registry[]` in `modules/fpga/fpga.c`,
    mirroring the existing KU15P entry. Set `proxy_bitstream` to
-   `NULL` for now; wire it up when you have one. Set quirks as
-   appropriate (e.g. `FPGA_QUIRK_CCLK_VIA_STARTUP` for any
+   `NULL` for now; wire it up when you have one. Set caveats as
+   appropriate (e.g. `FPGA_CAVEAT_CCLK_VIA_STARTUP` for any
    Xilinx 7-Series/UltraScale/UltraScale+).
 
 4. **Rebuild**. The registry is compile-time, no runtime registration.
diff --git a/modules/fpga/fpga.c b/modules/fpga/fpga.c
index 4639600..a17c189 100644
--- a/modules/fpga/fpga.c
+++ b/modules/fpga/fpga.c
@@ -21,7 +21,7 @@ static const fpga_target fpga_registry[] = {
         .ir_jshutdown     = 0x0D,
         .ir_isc_disable   = 0x16,
         .proxy_bitstream  = NULL,   /* TODO Phase 2.5: bscan_spi_xcku15p.bit */
-        .quirks           = FPGA_QUIRK_CCLK_VIA_STARTUP,
+        .caveats          = FPGA_CAVEAT_CCLK_VIA_STARTUP,
     },
     /* Xilinx Kintex UltraScale XCKU040 (KCU105 eval board)
      * IDCODE_REGISTER and INSTRUCTION_OPCODE values come from
@@ -41,7 +41,7 @@ static const fpga_target fpga_registry[] = {
         .ir_jshutdown     = 0x0D,
         .ir_isc_disable   = 0x16,
         .proxy_bitstream  = "bscan_spi_xcku040.bit",
-        .quirks           = FPGA_QUIRK_CCLK_VIA_STARTUP,
+        .caveats          = FPGA_CAVEAT_CCLK_VIA_STARTUP,
     },
 };
 
diff --git a/modules/fpga/fpga.h b/modules/fpga/fpga.h
index 0cd89ca..d5ec84b 100644
--- a/modules/fpga/fpga.h
+++ b/modules/fpga/fpga.h
@@ -9,7 +9,7 @@
  *   - private IR opcodes (USER1, CFG_IN, JPROGRAM, …) needed for
  *     configuration and for the BSCAN proxy bridge (Phase 2.5)
  *   - path to the BSCAN proxy bitstream
- *   - per-target quirks
+ *   - per-target caveats (known hardware gotchas)
  *
  * Adding an FPGA = one entry in fpga_registry[] + its .bsd in
  * bsdl_files/ + (optionally) its proxy .bit in bscan_proxies/.
@@ -24,8 +24,8 @@ typedef enum {
     FPGA_FAMILY_XILINX_USP,
 } fpga_family;
 
-/* Quirk flags */
-#define FPGA_QUIRK_CCLK_VIA_STARTUP   (1u << 0)  /* CCLK not directly drivable in EXTEST */
+/* Caveat flags: known hardware gotchas for a part. */
+#define FPGA_CAVEAT_CCLK_VIA_STARTUP   (1u << 0)  /* CCLK not directly drivable in EXTEST */
 
 typedef struct {
     const char    *name;             /* human-readable part name */
@@ -45,7 +45,7 @@ typedef struct {
     unsigned int   ir_isc_disable;
 
     const char    *proxy_bitstream;  /* path under bscan_proxies/, NULL if not yet available */
-    unsigned int   quirks;
+    unsigned int   caveats;          /* FPGA_CAVEAT_* flags */
 } fpga_target;
 
 /* Registry access */
diff --git a/modules/script/script.c b/modules/script/script.c
index 519041c..6045ac4 100644
--- a/modules/script/script.c
+++ b/modules/script/script.c
@@ -2795,10 +2795,10 @@ static int cmd_fpga_list(script_ctx *ctx, char *line)
             i, t->idcode, t->idcode_mask,
             t->name, fpga_family_name(t->family));
         ctx->script_printf(ctx, MSG_NONE,
-            "      bsdl=%s ir=%d proxy=%s quirks=0x%x\n",
+            "      bsdl=%s ir=%d proxy=%s caveats=0x%x\n",
             t->bsdl_filename, t->ir_length,
             t->proxy_bitstream ? t->proxy_bitstream : "(none yet)",
-            t->quirks);
+            t->caveats);
     }
     return JTAG_CORE_NO_ERROR;
 }
@@ -2831,9 +2831,9 @@ static int cmd_fpga_info(script_ctx *ctx, char *line)
             ctx->script_printf(ctx, MSG_INFO_0,
                 "Device %d  IDCODE 0x%.8lX  -> %s [%s]\n",
                 i, idcode, t->name, fpga_family_name(t->family));
-            if (t->quirks & FPGA_QUIRK_CCLK_VIA_STARTUP) {
+            if (t->caveats & FPGA_CAVEAT_CCLK_VIA_STARTUP) {
                 ctx->script_printf(ctx, MSG_NONE,
-                    "           quirk: CCLK routed via STARTUP primitive (not drivable in EXTEST)\n");
+                    "           caveat: CCLK routed via STARTUP primitive (not drivable in EXTEST)\n");
             }
         } else {
             ctx->script_printf(ctx, MSG_INFO_0,