diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3cb10d6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+Guidance for a coding agent working on **this plugin's own repository**. `CLAUDE.md` beside it only
+points here — the two harnesses discover different filenames and one set of instructions has to
+reach both.
+
+**This is not what the plugin is.** `README.md` answers that, for a person deciding whether to
+install it. This file answers "I have to change something in here — what will I break?"
+
+## Where you are
+
+A plugin repository, cloned into `~/officer-dev/plugins/music`, its own git remote. It is **not**
+part of the platform's repository, and `platform/plugins/music` is a different thing — that is
+where this plugin gets INSTALLED, by the installer cloning it from gitea. Never edit there; the
+next install overwrites it.
+
+Check the checkout with `bun run plugins:check` from the platform repo.
+
+## What it ships
+
+- `api/router.ts` — routes, mounted at `/api/music`
+- `sidecar/index.ts` — a process, run by PM2 as `officer-music`
+- `db/schema.ts` — tables: `music_favorites`, `music_playlists`, `music_playlist_items`, `music_now_playing`
+- `web/` — panels and a layout; the platform renders the screen, not this plugin
+
+Presence is the declaration: the platform decides what this plugin has by what files exist. Adding
+`db/schema.ts` gives it tables; deleting `api/router.ts` removes its routes. There is no field to
+keep in step.
+
+## What must not change without knowing why
+
+- **Permission key `music`** — stored as the subject of every grant. Renaming one is a data change, not a rename.
+- **Panel keys** (`music-browser`, `music-detail`) — a user's stored layout names them.
+- **Table names** — they hold real rows on installed machines.
+- **Host binaries** (`ffprobe`, `ffmpeg`) — declared in the manifest so an install can get them. Shelling out to something undeclared works on this machine and nowhere else.
+- **`appName`** — the directory name IS the id: route segment, table prefix, sidecar suffix, install key.
+
+## Verifying
+
+From the platform repo, which is where the toolchain lives:
+
+```bash
+bunx tsgo                 # a red typecheck is not done
+bun test                  # 1 known failure: ModelSelector, unrelated
+bun run plugins:check
+bunx prettier --write <the files you touched>
+```
+
+A sidecar change needs `pm2 restart officer-music`; anything in `api/` or `web/` needs
+`pm2 restart officer`.
+
+## Related
+
+- `README.md` — what it is and what it claims, for someone installing it
+- `PLUGIN.md` — this plugin's own reference: conventions and API surface
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8c36885
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,6 @@
+# CLAUDE.md
+
+**The instructions live in [`AGENTS.md`](AGENTS.md). Read it first — this file only points there.**
+
+Kept separate so agents that look for `AGENTS.md` by convention find the same guidance as those that
+look for `CLAUDE.md`, without the two drifting apart.