diff --git a/docs/BUILDING.md b/docs/BUILDING.md
index 53ca1ba..dd0672b 100644
--- a/docs/BUILDING.md
+++ b/docs/BUILDING.md
@@ -158,6 +158,17 @@ host test harness (`regtest`). Optional environment variables:
 
 - `ADRENO_LENIENT=1` drops a pass the encoder refuses instead of failing the
   command buffer. Use it for deployment; the tests use the strict default.
+- `ADRENO_PIPELINE=1` builds for the desktop AdrenoX2's IB pipeline (IOSurface
+  shadows wait for the GPU). The deployed plug-ins use it with `ADRENO_LENIENT=1`.
+- `ADRENO_SETTINGS_ICONS=1` encodes the CoreImage kernels of the icons inside
+  System Settings panes: sampled sRGB and grey+alpha textures, and multi-input
+  kernels once AdrenoX2 publishes `AdrenoIBComputeSamplers` (its
+  `ADRENO_IB_CS_SAMPLERS`, opted in with the guest boot-arg
+  `adreno_cs_samplers=1`). `tools/test-adreno-settings-icons.py` and
+  `tools/test-adreno-settings-ci-encoding.py` test it.
+
+`ADRENO_PIPELINE` and `ADRENO_SETTINGS_ICONS` take 0 or 1; 0 or unset leaves the
+build byte for byte as without them.
 - `ADRENO_SHADER_CACHE_PACK=<file>` links a precompiled shader pack into the
   bundle.
 - `ADRENO_COMPILER_RUNTIME=<dir>` bundles the air2ir3 runtime
diff --git a/docs/RUNNING.md b/docs/RUNNING.md
index ee2f083..8cd4dad 100644
--- a/docs/RUNNING.md
+++ b/docs/RUNNING.md
@@ -200,6 +200,21 @@ python3 tools/deploy-guest-plugin.py --device udp://<interface> \
 The tool checks every file against its expected base before writing anything,
 keeps backups, and can put them back with `--restore`.
 
+A plug-in that changes how icons render has no visible effect until the icons
+already rendered are dropped: IconServices keeps them in
+`/Library/Caches/com.apple.iconservices.store` and in each user's cache folder
+(`com.apple.iconservices`, `com.apple.iconservicesagent`), and the Dock keeps its
+own `com.apple.dock.iconcache` there. Rename them aside from the single-user
+shell, after the install and before the boot continues: run the tool without
+`--continue-boot`, rename the caches with `tools/guest-console.py --run` under the
+same `--owner`, then run the tool again with `--continue-boot` (it finds the files
+installed and only continues the boot).
+
+The kext side of the icons inside System Settings panes, `ADRENO_IB_CS_SAMPLERS`
+in the desktop AdrenoX2 profiles, is off unless the guest boots with
+`adreno_cs_samplers=1`. `tools/cycle.py` has no option that adds that boot-arg
+yet.
+
 ## Exit codes
 
 A boot reports why the guest stopped: