diff --git a/.claude-context/sessions/2026-04-06-cycle-effect-tag-colours.md b/.claude-context/sessions/2026-04-06-cycle-effect-tag-colours.md
new file mode 100644
index 0000000..f9d888b
--- /dev/null
+++ b/.claude-context/sessions/2026-04-06-cycle-effect-tag-colours.md
@@ -0,0 +1,42 @@
+# Cycle Effect, Tag Colour Library and Colour Editor
+
+**Date:** 2026-04-06
+**Project:** lego-dimensions-reader
+**Status:** resolved
+**Tags:** led-effects, cycle, tag-colors, tkinter, cli-client
+
+## Context
+Jess wanted a "revolving" light effect that chases around all three pads for certain characters, a themed colour entry for every character in the library, and a GUI to edit those colours. Adding the cycle effect exposed a removal bug: when a cycle tag was lifted, only its own pad cleared and the other two stayed frozen mid-cycle; and removing an unrelated tag could kill a running cycle.
+
+## Key Decisions
+- **Light only the pad the tag is on** for normal effects — earlier behaviour could affect other pads.
+- **`software_cycle` effect** tracked under a special internal key (`99`) so it's managed separately from per-pad effects; supports a `trail` parameter for a dim afterglow on inactive pads.
+- **Removal rules:**
+  - Remove a cycle tag → stop the cycle, clear all three pads, then re-apply themes for any tags still present.
+  - Remove a non-cycle tag while a cycle runs elsewhere → leave the LEDs alone.
+  - Normal removal → turn off just that pad.
+- **`builtin_led_effects` flag** lets external clients (the CLI client) disable the base reader's default LED behaviour so it doesn't override themes.
+- **Softer RGB values** — full-brightness multi-channel colours look washed out on the portal (e.g. cyan `[0,255,255]` → `[0,180,160]`).
+- **Dedicated Tag Colour Editor (tkinter)** rather than hand-editing JSON.
+
+## Technical Details
+- `tag_colors.json` — 82 themed tag mappings (colour, effect, speed, optional cycle/trail).
+- `dimensions_cli_client.py` — CLI client that sends card IDs to Moonlight (`POST /api/video/play`, port 8547) and applies themed effects; supports cycle.
+- `tag_color_editor.py` — GUI for editing `tag_colors.json`.
+
+## Code Changes
+- `lego_dimensions_reader.py` — per-pad lighting fix; `software_cycle` effect.
+- `dimensions_cli_client.py` — cycle support; restore other pads on cycle removal; don't kill cycle on non-cycle removal.
+- `tag_color_editor.py` — new.
+- `tag_colors.json` — complete 82-entry set.
+- `README.md` — cycle effect examples.
+
+## Open Questions / Next Steps
+- Separate idea: figures on a reader pad switching Zigbee smart plugs (Tuya gateway + `tinytuya` cloud mode). Hardware bought, not yet paired; needs Tuya IoT developer credentials (`<redacted>`) and plug names before a mapping module can be built.
+
+## Artifacts
+- `2b4ca64` — Restore other pads when cycle effect tag is removed
+- `ac190d4` — Don't kill cycle effect when removing non-cycle tags
+- `692c149` — Add software_cycle effect
+- `c7dd1a6` — Add Tag Color Editor GUI tool
+- `65512de` — Complete tag_colors.json with 82 themed tag mappings