fixes

docs/ARCHITECTURE.md

@@ -35,3 +35,9 @@ and compresses it with zstd to `.pkg`.
 ```
 
 The exact RustProxy SHA and package version are written to `dist/BUILD-INFO.txt`.
+
+## Build-only FreeBSD patch layer
+
+RustProxy upstream is kept unchanged. Before Docker compilation, the Debian builder copies the checked-out source into a temporary directory under `dist/.build-source/` and applies version-specific patches from `builder/freebsd/patches/<version>/`. Docker receives the temporary copy read-only. The temporary tree is removed after the build.
+
+For RustProxy 0.20.0 the patch is `builder/freebsd/patches/0.20.0/0001-opnsense-build.patch`. This makes the FreeBSD/OPNsense compatibility changes part of the packaging repository rather than the RustProxy repository.

docs/FIRST_RUN.md

@@ -154,3 +154,35 @@ The RustProxy administration UI is reachable from other hosts by default on port
 Direct `pkg add` is supported: the package post-install script restarts OPNsense `configd`, flushes the plugin cache and renders `/usr/local/etc/rustproxy/opnsense.conf` so `configctl rustproxy status/start/stop` is available immediately.
 
 RustProxy requires its data directory to be private. The plugin enforces owner `rustproxy:rustproxy` and mode `0700` on `/var/db/rustproxy` before every start.
+
+## FreeBSD patch set
+
+The OPNsense builder automatically applies version-specific RustProxy patches to a temporary build copy only. The application checkout remains clean:
+
+```bash
+cd /opt/opn-rustproxy/source/RustProxy
+git status
+```
+
+For RustProxy 0.20.0 the builder uses:
+
+```text
+builder/freebsd/patches/0.20.0/0001-opnsense-build.patch
+```
+
+The normal setting is:
+
+```bash
+APPLY_FREEBSD_PATCHES=1
+```
+
+During a build you should see:
+
+```text
+Applying FreeBSD/OPNsense patch set for RustProxy 0.20.0 to isolated build source...
+  applied: 0001-opnsense-build.patch
+```
+
+## Runtime directory
+
+`/var/run/rustproxy` is created automatically as `rustproxy:rustproxy` with mode 0750 during package installation and before each service start. PID files are `daemon.pid` and `rustproxy.pid` inside that directory.