diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..b865fa5
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,55 @@
+# AGENTS.md
+
+## Repository Role
+
+This repository contains:
+
+- runtime files
+- configs
+- quests and locale data
+- Debian `systemd` deployment files
+- operational docs
+- root-only login healthcheck wrapper
+
+This is the runtime/deployment side of the stack, not the C++ source repository.
+
+## Working Rules
+
+- Do not commit production secrets.
+- Do not commit host-specific overrides unless they are intended defaults.
+- Do not commit generated runtime state such as live `channels/`, `pids.json`, or quest build output.
+- Keep operational docs under `docs/` in sync with deployment changes.
+
+## Important Directories
+
+- `deploy/systemd/`: versioned Debian units and installer
+- `deploy/healthcheck/`: root-only operational login check wrapper
+- `docs/`: Debian/Linux-first operational documentation
+- `share/conf/`: legacy runtime config files
+- `sql/`: schema/bootstrap reference files
+
+## Current Production Reality
+
+The current VPS uses:
+
+- runtime root: `/home/mt2.jakubkadlec.dev/metin/runtime/server`
+- installed healthcheck: `/usr/local/sbin/metin-login-healthcheck`
+
+Changes to `deploy/systemd/` or healthchecks should be validated on the VPS after merge.
+
+## Verification After Risky Changes
+
+For runtime/deploy changes, verify with:
+
+```bash
+systemctl restart metin-server.service
+systemctl status metin-server.service --no-pager
+/usr/local/sbin/metin-login-healthcheck
+```
+
+## Cross-Repo Boundaries
+
+- C++ server logic belongs in `m2dev-server-src`
+- runtime/config/deploy/docs belong here
+- client protocol code belongs in `m2dev-client-src`
+- client assets and root python files belong in `m2dev-client`
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..57c60a1
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,10 @@
+# CLAUDE.md
+
+Follow [AGENTS.md](AGENTS.md) as the canonical repo guide.
+
+Short version:
+
+- this repo owns runtime files, deployment, docs, and operational wrappers
+- never commit real production secrets
+- keep `docs/` updated when changing deploy/runtime behavior
+- validate `systemd` and login-healthcheck changes on the Debian VPS