diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..95868b0
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,94 @@
+# AGENTS.md
+
+Operational guide for AI agents working on this repository.
+
+## Remote machine
+
+The plugin runs on **jozz** (`vini@jozz`). SSH access is pre-configured; no password needed.
+
+```bash
+ssh vini@jozz "some command"
+```
+
+## Deploy cycle
+
+After editing any file under `plugin/`, commit, push, then run on jozz:
+
+```bash
+git push && ssh vini@jozz "bash -s" <<'EOF'
+git -C "$HOME/skeledance" pull
+cp -r "$HOME/skeledance/plugin/." "$HOME/.local/share/plasma/wallpapers/com.vini.dancingcharacter/"
+export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus
+qdbus6 org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.refreshCurrentShell 2>&1
+echo "done"
+EOF
+```
+
+The `qdbus6` call hot-reloads QML. For HTML/CSS/JS changes the page reloads automatically. If visuals look wrong after deploy, wait a few seconds — WebEngine takes a moment to reinitialize.
+
+## Services on jozz
+
+### music-light
+
+Reads the current track via `playerctl`, extracts the dominant album color, and exposes it over HTTP.
+
+```bash
+# Status
+ssh vini@jozz "systemctl --user status music-light.service"
+
+# Restart (needed after updating luz-musica.py)
+ssh vini@jozz "systemctl --user restart music-light.service"
+
+# Logs
+ssh vini@jozz "journalctl --user -u music-light.service -n 30 --no-pager"
+```
+
+Endpoints (all on `127.0.0.1:8765`):
+
+| Path | Description |
+|------|-------------|
+| `GET /current` | Returns `{"art_url": "...", "rgb": [r, g, b]}` for the playing track |
+| `GET /art?t=` | Proxies the album art image bytes (use query string for cache-busting) |
+
+**CORS**: `Access-Control-Allow-Origin: *` is set on all responses. Required because `dancer.html` is loaded from `file://`.
+
+**Deploying changes to luz-musica.py**: `scp` the file, then restart the service. The repo at `~/music-light` on jozz may be behind; always `scp` directly.
+
+```bash
+scp /home/ltadeu6/Projetos/Codigo/music-light/luz-musica.py vini@jozz:~/music-light/luz-musica.py
+ssh vini@jozz "systemctl --user restart music-light.service"
+```
+
+### cava-server
+
+Started automatically by the wallpaper via `cava-start.sh` on load. Reads CAVA audio bars from stdin and streams them as SSE on `127.0.0.1:5555`.
+
+```bash
+# Check if running
+ssh vini@jozz "pgrep -a python | grep cava"
+
+# Restart manually if bars stop animating
+ssh vini@jozz "bash ~/.local/share/plasma/wallpapers/com.vini.dancingcharacter/contents/ui/cava-start.sh &"
+```
+
+## Debugging JS errors
+
+Add a `onJavaScriptConsoleMessage` handler to `main.qml` to capture JS errors to a file:
+
+```qml
+onJavaScriptConsoleMessage: function(level, message, lineNumber, sourceID) {
+    var logDs = Qt.createQmlObject('import org.kde.plasma.plasma5support as P5S; P5S.DataSource { engine: "executable" }', webView)
+    logDs.connectSource("echo '[skeledance] " + message.replace(/'/g, '') + " :" + lineNumber + "' >> /tmp/skeledance_console.log")
+}
+```
+
+Then read on jozz: `ssh vini@jozz "cat /tmp/skeledance_console.log"`.
+
+**Remove the handler after debugging** — it creates a new QmlObject per message and causes performance issues.
+
+## Known WebEngine constraints
+
+- `fetch()` to `http://` works from `file://` pages when `localContentCanAccessRemoteUrls: true` is set in QML.
+- `<img src="http://...">` also works with `localContentCanAccessRemoteUrls: true`, but the server must include `Access-Control-Allow-Origin: *`.
+- `CSS background-image: url('http://...')` is blocked — use `<img>` or `fetch()+blob URL` instead.
+- `img.src` with `file:///` paths works when `localContentCanAccessFileUrls: true` is set.