diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..a4ebeba
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# Agent Instructions
+
+## Project
+
+Monitor is a self-hosted network path quality monitor. Backend coordinates Agents and Probes, stores measurements, and serves the REST/SSE API. `web/display` is the read-only overview; `web/admin` manages nodes, tests, and settings.
+
+## Branch and workspace safety
+
+- Treat `main` as the stable release branch and `dev` as the integration branch. Keep ordinary implementation work on `dev` or a feature branch; integrate into `main` through a pull request.
+- Before editing, inspect `git status`. Preserve pre-existing user changes: do not reset, clean, stash, or include unrelated files in a commit.
+- Do not commit credentials, API keys, registry passwords, or generated runtime data. CI credentials belong in Woodpecker secrets.
+- Keep development OCI images in the `monitor-dev/` repository path and release images in `monitor/`. Do not let a development build overwrite release tags such as `latest`.
+
+## Project layout
+
+- `backend/src/Monitor.Backend/`: service entry point and composition.
+- `backend/src/Monitor.Backend.Api/`: REST endpoints, contracts, and OpenAPI.
+- `backend/agent/`, `backend/probe/`: node applications and their READMEs.
+- `backend/fleet/`, `backend/shared/`: reusable node framework, measurement engine, protocols, and data formats.
+- `web/display/`, `web/admin/`: Vite applications; `web/shared/`: API client, generated types, charts, and shared UI.
+- `packaging/`, `scripts/`, `.woodpecker/`, `docs/`: container/package builds, CI workflows, and project documentation.
+
+## Local development and builds
+
+Requirements: .NET SDK 10 and Node.js/npm. The SDK selection is defined by `backend/global.json`.
+
+- Backend build: `cd backend && dotnet build Monitor.slnx -c Release`
+- Backend tests: `cd backend && dotnet test --solution Monitor.slnx -c Release`
+- Frontend dependencies/build: `npm ci --prefix web && npm run build --prefix web`
+- Frontend style check: `npm run lint:css --prefix web`
+- Local backend: from `backend/`, run `dotnet run --project src/Monitor.Backend -- --urls http://localhost:5000`.
+- Local web apps: from the repository root, run `npm ci --prefix web` then `npm run dev --prefix web`. The current dev config uses display port 5173 and admin port 5175; `/admin/` is proxied through the display server. Check the Vite configs when working on another branch because ports can differ.
+- After changing API contracts, regenerate/check `backend/openapi/v1.json` and run `npm run gen:api --prefix web` so frontend API types stay aligned.
+
+Follow the user's requested validation scope. Do not start a full tag/release build unless requested.
+
+## CI and releases
+
+CI triggers and image tags can change; inspect `.woodpecker/*.yml` and `docs/deployment.md` before changing or describing them. In particular, check the distinction between `[CI]` main builds, `[SKIP TESTS]`, and version-tag releases in the current branch.
+
+A version tag `vMAJOR.MINOR.PATCH` runs the full cross-platform release pipeline. Development image builds and releases must remain isolated in their respective Zot repository paths.