diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2542fdf
--- /dev/null
+++ b/README.md
@@ -0,0 +1,52 @@
+# RaidVisuals-OctoWoW
+
+This is an OctoWoW-specific baseline fix for [MarcelineVQ/twow-raid-visuals](https://github.com/MarcelineVQ/twow-raid-visuals).
+
+## The problem
+
+`patch-O.mpq` (raid-visuals) ships **full-replacement copies** of 9 client DBC files:
+`AreaTrigger`, `CreatureModelData`, `CreatureSoundData`, `SoundEntries`, `Spell`,
+`SpellIcon`, `SpellVisual`, `SpellVisualEffectName`, `SpellVisualKit`.
+
+These were frozen from a Turtle WoW `1.18.0` snapshot. Because MPQ patches replace
+whole files (not merge rows), any OctoWoW client running patch-O silently loses
+**any DBC content OctoWoW added after that snapshot was taken** — since the
+patched table simply doesn't have those newer rows.
+
+**Concrete symptom:** summoning the "Buccaneer Bubbles" companion (item 98800,
+a team-exclusive pet) crashed clients with an ACCESS_VIOLATION, and the
+companion didn't even show up in the spellbook. Root cause: its model
+(`CreatureModelData` IDs 2766/2767, `BabyOctopus`/`BabyOctopusPurple`) doesn't
+exist in the frozen table raid-visuals ships. `Spell.dbc` alone was also
+missing **71 spell records** OctoWoW has added since the snapshot.
+
+## The fix
+
+The `dbc/` folder in this repo holds **OctoWoW's current live DBC baseline**
+for these 9 tables (extracted from OctoWoW's own client patch files), instead
+of the frozen Turtle WoW snapshot.
+
+`patches/` and `schema/` are **unchanged from upstream** — none of raid-visuals'
+actual visual/sound logic was touched. Every boss AoE indicator, icon fix, and
+sound tweak (duck mute, kodo footsteps, murloc dance, etc.) still applies
+exactly as before; only the foundation they're layered on top of changed.
+
+`built/` contains the already-patched output (baseline + all patches applied)
+— these are the exact files currently shipped inside the fixed `patch-O.mpq`
+release. If you have the original `wow_dbc_patcher` tool, running it with
+`--dbc-dir dbc/` against this repo's `patches/`/`schema/` should reproduce
+`built/` exactly.
+
+## Two open questions for the dev team
+
+1. **This baseline will go stale again** the next time OctoWoW adds content
+   that lands in one of these 9 tables (new pets/mounts/spells especially).
+   Worth deciding on a process to periodically re-sync `dbc/` against
+   whatever OctoWoW's client currently ships.
+2. Two of the "live" files I initially pulled (`CreatureSoundData.dbc`,
+   `SpellVisualEffectName.dbc`) turned out to be **older/incomplete**
+   compared to even the frozen Turtle WoW snapshot (missing records the
+   frozen version had, e.g. the duck sound entry). I don't know which
+   OctoWoW client file is the true current authoritative source for these
+   two tables — if someone on the dev side can point to the right one,
+   `dbc/` should be updated accordingly.