diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..4e4d5ad
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+NetEase-MusicBox is a Python 3.10+ command-line/curses TUI music player, managed with
+[`uv`](https://docs.astral.sh/uv/). There is a single package (`NEMbox`) and one product
+(the `musicbox` CLI/TUI). Dependencies are refreshed automatically by the startup update
+script (`uv sync --frozen`); you do not need to reinstall them.
+
+### Running the app
+- Interactive TUI: `uv run musicbox` — this uses `curses` and requires a real interactive
+  terminal (TTY). It will not render in a non-TTY/headless shell; use the CLI subcommands
+  below for scripted/agent verification instead.
+- Agent/CLI mode (no TTY needed): `uv run musicbox <command>`, e.g.
+  `search`, `song url`, `play`, `pause`, `status`, `queue`, `daemon`, `auth`.
+  Add `--json` for machine-readable output. See `README.md` for the full command list.
+- Playback runs through a background daemon; `musicbox play --id <id>` auto-starts it and
+  `musicbox daemon stop` stops it.
+
+### Audio backends (system deps, NOT in update script)
+- `mpg123` (MP3) and `mpv` (FLAC / Hi-Res) are OS packages installed via `apt-get`
+  (`sudo apt-get install -y mpg123 mpv`). They are pre-installed in the snapshot; reinstall
+  only if `musicbox play` reports a missing backend. Playback selects `mpg123` by default.
+
+### Network / API note
+- Song search and playable URLs come from NetEase's public API, which only accepts
+  China-region access. From other regions requests can fail or return empty; set an HTTP
+  proxy (see README "配置") if search stops returning results. In this environment the API
+  was reachable and returned live results.
+- Login is QR-code scan only (renders a QR block in the terminal); there is no
+  username/password login and no test-login secret is required for search/playback.
+
+### Lint / test / build
+Standard commands (already documented in `.cursor/rules/pre-commit-validation.mdc` and
+`.github/workflows/ci.yml`); run them via `uv run`:
+- `uv run ruff check`
+- `uv run ruff format --check`
+- `uv run ty check` — emits ~11 diagnostics that are configured as `warn` in
+  `pyproject.toml`; it exits 0 and is not a failure.
+- `uv run pytest -q --tb=short`
+- `uv build`