diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000..add09af6
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,54 @@
+# AGENTS.md (3x-ui)
+
+This repo is **primarily Go**: a Gin-based web panel that manages an **Xray-core** process and stores state in a **SQLite** DB.
+
+## Quick commands (repo root)
+
+- **Run (dev, no root needed)**:
+  - Ensure writable paths:
+    - `mkdir -p ./x-ui ./bin ./log`
+    - `export XUI_DB_FOLDER="$(pwd)/x-ui"`
+    - `export XUI_BIN_FOLDER="$(pwd)/bin"`
+    - `export XUI_LOG_FOLDER="$(pwd)/log"`
+    - `export XUI_DEBUG=true` (loads templates/assets from disk; see `web/AGENTS.md`)
+  - Start: `go run .`
+  - Panel defaults (fresh DB): `http://localhost:2053/` with **admin/admin**
+
+- **Build**: `go build -ldflags "-w -s" -o build/x-ui main.go`
+- **Format**: `gofmt -w .`
+- **Tests**: `go test ./...`
+- **Basic sanity**: `go vet ./...`
+
+## Docker
+
+- **Compose**: `docker compose up --build`
+  - Uses `network_mode: host` and mounts:
+    - `./db/` → `/etc/x-ui/` (SQLite DB lives at `/etc/x-ui/x-ui.db`)
+    - `./cert/` → `/root/cert/`
+
+## Layout / where things live
+
+- **Entry point**: `main.go` (starts the web server + subscription server; handles signals)
+- **Config**: `config/` (env-driven defaults; DB path, bin path, log folder)
+- **DB (SQLite via GORM)**: `database/` (+ `database/model/`)
+- **Web panel**: `web/` (Gin controllers, templates, embedded assets, i18n)
+- **Subscription server**: `sub/`
+- **Xray process management**: `xray/` (binary path naming, config/log paths, process wrapper)
+- **Operational scripts**: `install.sh`, `update.sh`, `x-ui.sh` (production/admin tooling; be cautious editing)
+
+## Important environment variables
+
+- **`XUI_DEBUG=true`**: enables dev behavior (Gin debug + loads `web/html` and `web/assets` from disk).
+- **`XUI_DB_FOLDER`**: DB directory (default: `/etc/x-ui` on non-Windows). DB file is `<folder>/x-ui.db`.
+- **`XUI_BIN_FOLDER`**: where Xray binary + `config.json` + `geo*.dat` live (default: `bin`).
+- **`XUI_LOG_FOLDER`**: log directory (default: `/var/log` on non-Windows).
+- **`XUI_LOG_LEVEL`**: `debug|info|notice|warning|error`.
+
+## Agent workflow guidelines
+
+- **Prefer small, surgical changes**: this is a production-oriented project (panel + system scripts).
+- **Don’t run** `install.sh` / `update.sh` in dev automation: they expect **root** and mutate the system.
+- **When touching templates/assets**: ensure it works in both **debug** (disk) and **production** (embedded) modes.
+- **Security**: treat any change in `web/controller`, `web/service`, and shell scripts as security-sensitive.
+
+
diff --git a/web/AGENTS.md b/web/AGENTS.md
new file mode 100644
index 00000000..d3c36bc9
--- /dev/null
+++ b/web/AGENTS.md
@@ -0,0 +1,23 @@
+# AGENTS.md (web/)
+
+`web/` is the **Go web panel** (Gin) and includes **embedded** templates/assets for production.
+
+## Templates & assets
+
+- **Templates**: `web/html/**` (server-rendered HTML templates containing Vue/Ant Design UI markup).
+- **Static assets**: `web/assets/**` (vendored JS/CSS/libs).
+- **Embedding**:
+  - Production uses `//go:embed` for `assets`, `html/*`, and `translation/*` (see `web/web.go`).
+  - Dev mode (`XUI_DEBUG=true`) loads templates from disk (`web/html`) and serves assets from disk (`web/assets`).
+
+## i18n / translations
+
+- Translation files live in `web/translation/*.toml` and are embedded.
+- When adding UI strings, update the relevant TOML(s) and keep keys consistent across languages.
+
+## Common dev pitfalls
+
+- Run from repo root when `XUI_DEBUG=true` so `web/html` and `web/assets` resolve correctly.
+- Some functionality depends on an Xray binary in `XUI_BIN_FOLDER` (default `bin/`); the panel can run without Xray but Xray-related features will fail until it’s available.
+
+
diff --git a/xray/AGENTS.md b/xray/AGENTS.md
new file mode 100644
index 00000000..92c02721
--- /dev/null
+++ b/xray/AGENTS.md
@@ -0,0 +1,19 @@
+# AGENTS.md (xray/)
+
+`xray/` wraps **Xray-core process management** (start/stop/restart, API traffic reads) and defines where runtime files live.
+
+## Runtime file paths (via `config/`)
+
+- **Binary**: `XUI_BIN_FOLDER/xray-<goos>-<goarch>`
+  - Example on Linux amd64: `bin/xray-linux-amd64`
+- **Config**: `XUI_BIN_FOLDER/config.json`
+- **Geo files**: `XUI_BIN_FOLDER/{geoip.dat,geosite.dat,...}`
+- **Logs**: `XUI_LOG_FOLDER/*` (default `/var/log` on non-Windows)
+
+## Notes for changes
+
+- Keep OS/arch naming consistent with `GetBinaryName()` (`xray-<GOOS>-<GOARCH>`).
+- The web panel may attempt to restart Xray periodically; if the binary is missing, Xray-related operations will fail but the panel can still run.
+- Be careful with process/exec changes: they are security- and stability-sensitive.
+
+