Index: pkg/README
===================================================================
RCS file: /cvs/ports/devel/codex/pkg/README,v
diff -u -p -u -r1.2 README
--- pkg/README	24 Aug 2026 16:39:57 -0000	1.2
+++ pkg/README	28 Aug 2026 19:26:48 -0000
@@ -14,9 +14,60 @@ one you should add into ~/.codex/config.
 	base_url = "http://127.0.0.1:8080/v1"
 	wire_api = "responses"
 
-${PKGSTEM} uses a lot of memory, it starts with 256Mb per agent/worker
-thread, and you may need to bump your limits (`ulimit -d`) or raise
-datasize limit in used login class..
+Resource limits
 
-Also, ${PKGSTEM} may use a lot of open files, you may need to raise both
-the system-wide maxfiles and used login class limits.
+Codex can spawn multiple subprocesses (shell, ripgrep, git, python,
+etc.), run several agents in parallel, and use a significant number of
+file descriptors and a lot of memory when working on large
+repositories. On current OpenBSD, the default login class limits
+datasize to 1536M, maxproc to 128 and openfiles to 512. Small sessions
+fit within these limits, but large or highly parallel Codex workloads
+may hit them.
+
+Recommended login class
+
+If Codex fails to spawn processes, runs out of memory, or reports
+"too many open files", consider creating a dedicated login class
+instead of raising the limits of every user. Add this to
+/etc/login.conf:
+
+codex:\
+	:openfiles-cur=1024:\
+	:openfiles-max=2048:\
+	:maxproc-cur=512:\
+	:maxproc-max=1024:\
+	:datasize-cur=8G:\
+	:datasize-max=16G:\
+	:stacksize-cur=8M:\
+	:stacksize-max=16M:\
+	:tc=default:
+
+Rebuild the login class database so the change takes effect:
+
+	# cap_mkdb /etc/login.conf
+
+Apply the class
+
+Assign the class to the user who runs Codex:
+
+	# usermod -L codex <user>
+
+Start a new login session afterwards: log out and log in again so
+that the new limits are applied. Merely starting a new shell does not
+update the login class of the current session.
+
+Verify
+
+Check the effective limits from the user's session:
+
+	$ ulimit -a
+
+The relevant entries are nofiles (openfiles), processes (maxproc) and
+data (datasize). In the default ksh you can also query them
+individually with `ulimit -n`, `ulimit -p` and `ulimit -d`.
+
+Increase these values only as needed; the values above are starting
+points for heavier workloads. Login-class limits are preferable to
+raising system-wide kernel limits; consider kern.maxproc and
+kern.maxfiles only if the kernel limits turn out to be the actual
+bottleneck after raising the login class.