docs: add comprehensive agent guide for um-cli, detailing architecture, commands, and conventions

README.md

@@ -11,8 +11,11 @@ Original: Web Edition https://git.um-react.app/um/web
 
 ## Features
 
-- [x] All Algorithm Supported By `unlock-music/web`
-- [x] Complete Metadata & Cover Image
+- Decrypt formats supported by `unlock-music/web` (NCM, QMC/MGG/MFLAC, KGM/KGG, KWM, XM, Ximalaya, TM, …)
+- Optional network metadata & cover update via `--update-metadata` (requires `ffmpeg` / `ffprobe` on `PATH`)
+- Directory watch mode (`--watch`), overwrite / remove-source helpers
+- QMC ekey loaders: platform defaults (macOS / Windows), user MMKV, Android `player_process_db`
+- KGG (KGMv5) on Windows via KuGou `KGMusicV3.db`
 
 ## Release
 
@@ -20,19 +23,43 @@ Original: Web Edition https://git.um-react.app/um/web
 
 ## Install from source
 
-- Requirements: **Golang 1.23.3**
+- Requirements: **Go 1.25+** (see `go.mod`)
 
-1. run `go install git.um-react.app/um/cli/cmd/um@main`
+```bash
+go install git.um-react.app/um/cli/cmd/um@main
+```
 
 ### Build from repo source
 
-1. Pull repo source.
-2. Build with `go build ./cmd/um`.
+```bash
+git clone https://git.um-react.app/um/cli.git
+cd cli
+go build -o um ./cmd/um
+```
 
-It will produce `um` or `um.exe` (Windows).
+Produces `um` (or `um.exe` on Windows).
 
 ## How to use
 
-- Drag the encrypted file to `um.exe` (Tested on Windows)
-- Run: `./um [-o <output dir>] [-i] <input dir/file>`
-- Use `./um -h` to show help menu
+```bash
+# Single file or directory (default input = cwd, default output = input dir)
+./um [-o <output dir>] [-i] <input dir/file>
+
+# Common flags
+./um -o ./out --overwrite ./encrypted/
+./um --watch -o ./out ./inbox/                 # process existing + watch for new files
+./um --update-metadata -o ./out song.mflac     # needs ffmpeg/ffprobe
+./um --supported-ext                           # list registered extensions
+./um -h
+```
+
+Drag-and-drop onto `um.exe` also works on Windows (passes the path as argv).
+
+## Development
+
+See [AGENTS.md](./AGENTS.md) for repository layout, how to add a decoder, and agent-oriented conventions.
+
+## License
+
+This project is licensed under the MIT License.  
+See the [LICENSE](./LICENSE) file for details.