I think this wording clarifies what's happening.
1. Start by talking about creating a new environment. That's what we always
do. Everything afterwards is an operation performed on this new environment.
2. Move the list of magic variables out of doas.conf. I think it's better to
document this in one place. Note that setenv comes after everything else.
3. Add DOAS_USER to the list of variables set.
Index: doas.1
===================================================================
RCS file: /cvs/src/usr.bin/doas/doas.1,v
retrieving revision 1.21
diff -u -p -r1.21 doas.1
--- doas.1 19 Jun 2019 09:50:13 -0000 1.21
+++ doas.1 21 Jun 2019 16:46:28 -0000
@@ -40,7 +40,7 @@ or
.Fl s
is specified.
.Pp
-By default, the environment is reset.
+By default, a new environment is created.
The variables
.Ev HOME ,
.Ev LOGNAME ,
@@ -51,6 +51,9 @@ and
and the
.Xr umask 2
are set to values appropriate for the target user.
+.Ev DOAS_USER
+is set to the name of the user executing
+.Nm .
The variables
.Ev DISPLAY
and
Index: doas.conf.5
===================================================================
RCS file: /cvs/src/usr.bin/doas/doas.conf.5,v
retrieving revision 1.38
diff -u -p -r1.38 doas.conf.5
--- doas.conf.5 19 Jun 2019 09:55:55 -0000 1.38
+++ doas.conf.5 21 Jun 2019 16:46:28 -0000
@@ -49,22 +49,11 @@ The user is not required to enter a pass
After the user successfully authenticates, do not ask for a password
again for some time.
.It Ic keepenv
-The user's environment is maintained.
-The default is to retain the variables
-.Ev DISPLAY
-and
-.Ev TERM
-from the invoking process, reset
-.Ev HOME ,
-.Ev LOGNAME ,
-.Ev PATH ,
-.Ev SHELL ,
-and
-.Ev USER
-as appropriate for the target user, and discard the rest of the environment.
+Environment variables other than those listed in
+.Xr doas 1
+are retained when creating the environment for the new process.
.It Ic setenv { Oo Ar variable ... Oc Oo Ar variable=value ... Oc Ic }
-In addition to the variables mentioned above, keep the space-separated
-specified variables.
+Keep or set the space-separated specified variables.
Variables may also be removed with a leading
.Sq -
or set using the latter syntax.
@@ -74,6 +63,7 @@ is a
.Ql $
then the value to be set is taken from the existing environment
variable of the indicated name.
+This option is processed after the default environment has been created.
.El
.It Ar identity
The username to match.
