From a7bb6454a45d479047c35850bb7756320240db4d Mon Sep 17 00:00:00 2001
From: TapTap <taptap.programming@gmail.com>
Date: Sun, 19 Jul 2026 20:43:54 +0200
Subject: [PATCH] docs: add AGENTS.md with custom-image dependency install rule

---
 .opencode/agents/architect.md    |  2 ++
 .opencode/agents/cmake-expert.md |  1 +
 AGENTS.md                        | 33 ++++++++++++++++++++++++++++++++
 3 files changed, 36 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/.opencode/agents/architect.md b/.opencode/agents/architect.md
index fae37a4..f22a997 100644
--- a/.opencode/agents/architect.md
+++ b/.opencode/agents/architect.md
@@ -9,6 +9,8 @@ You are a system architect for the FastSync project — a high-performance file
 
 Make high-level design decisions. Evaluate trade-offs, plan module interactions, design data flow, and ensure architectural coherence across the codebase.
 
+> **Environment rule:** dependency installation must always use the project's custom Docker image (repo-root `Dockerfile`, same as CI) — never ad-hoc host package installs. See `AGENTS.md`.
+
 ## Project Architecture
 
 ### Module Map
diff --git a/.opencode/agents/cmake-expert.md b/.opencode/agents/cmake-expert.md
index 7ae2056..581629b 100644
--- a/.opencode/agents/cmake-expert.md
+++ b/.opencode/agents/cmake-expert.md
@@ -69,6 +69,7 @@ tests/         — test sources (globbed as TEST_SRCS)
 - Include directories: `src/shared`, `src/server`, `src/client`, `tests` (for test target).
 - Sanitizer support is commented out but present (`-fsanitize=address`).
 - Build with `cmake -B build -S . && cmake --build build -j$(nproc)`.
+- Install dependencies only via the project's custom Docker image (repo-root `Dockerfile`, same image CI uses) — never via host package installs; see `AGENTS.md`.
 
 ## When Making Changes
 
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..7b600c1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# AGENTS.md
+
+FastSync is a high-performance file synchronization system written in C11. It supports TCP and SSH transports, TLS encryption (OpenSSL), streaming zstd compression, multithreaded transfers, and incremental sync. The build uses CMake; CI runs on Gitea Actions (`.gitea/workflows/ci.yaml`).
+
+## Dependency installation
+
+**Rule: always install dependencies using the project's custom Docker image — never via ad-hoc system package installs on the host** (no `apt-get install` / `pip install` on the host machine).
+
+The image is built from the repo-root `Dockerfile` and is the same image CI uses: `gitea.tap-tap.win/taptap/fastsync-ci:v7`. It contains the full toolchain: gcc/g++, CMake, libzstd-dev, libssl-dev, make, git, cppcheck, clang-format, python3 + pytest, openssh-client, and Node.js.
+
+```bash
+# Build the image from the repo-root Dockerfile
+docker build -t fastsync-ci:local .
+
+# Provision dependencies and build inside the container (repo mounted at /workspace)
+docker run --rm -v "$PWD:/workspace" -w /workspace fastsync-ci:local \
+  sh -c 'cmake -B build -S . && cmake --build build -j$(nproc)'
+```
+
+If a dependency is missing from the image, add it to the `Dockerfile` (and rebuild) rather than installing it on the host.
+
+## Build
+
+```bash
+cmake -B build -S . && cmake --build build -j$(nproc)
+```
+
+## Test
+
+```bash
+./build/tests                # unit tests
+python3 -m pytest tests/     # integration tests
+```