diff --git a/docs/gateway.md b/docs/gateway.md
index ebb0cf2f..1c59997a 100644
--- a/docs/gateway.md
+++ b/docs/gateway.md
@@ -351,36 +351,38 @@ required.
 ```nix
 services.hyperhive.gateway.auth = {
   enable = true;
-  htpasswdFile = "/etc/hyperhive/gateway.htpasswd";
   # realm = "hyperhive";  # optional, default shown
 };
 ```
 
-Manage users with `hivectl gateway`:
+The credential store lives at the fixed path
+`/var/lib/hyperhive/gateway/gateway.htpasswd` on the host. A tmpfiles
+rule pre-creates the file on first boot; no manual path configuration
+is required. The file is exposed inside the gateway container at
+`/run/hive-state/gateway.htpasswd` via the existing gateway state
+bind-mount.
+
+Manage users with `hivectl gateway` (defaults to the standard path — no
+`--file` flag needed for the common case):
 
 ```sh
 # Add or update a user (prompted for password):
-hivectl gateway create-user --file /etc/hyperhive/gateway.htpasswd alice --password-stdin
+hivectl gateway create-user alice --password-stdin
 
 # Add with inline password (visible in shell history — avoid for sensitive creds):
-hivectl gateway create-user --file /etc/hyperhive/gateway.htpasswd bob --password hunter2
+hivectl gateway create-user bob --password hunter2
 
 # Remove a user:
-hivectl gateway delete-user --file /etc/hyperhive/gateway.htpasswd bob
+hivectl gateway delete-user bob
 
 # List current usernames:
-hivectl gateway list-users --file /etc/hyperhive/gateway.htpasswd
+hivectl gateway list-users
 ```
 
 `hivectl gateway create-user` hashes passwords with BCrypt (cost 12) and
 writes `$2y$`-prefixed hashes that nginx accepts natively. No external
-`htpasswd` binary is required. The file is created on first add if absent;
-its parent directory must already exist.
-
-The file must be readable by the `nginx` user inside the container
-(`chmod 0644`). The module bind-mounts the file's parent directory
-read-only into the container at `/run/gateway-auth/`; nginx reads
-`/run/gateway-auth/<filename>`.
+`htpasswd` binary is required. Pass `--file <path>` to target a
+non-default file.
 
 **What is not gated:** per-agent UI routes emitted into `agents.conf`
 (served under `/agent/<name>/`) inherit no auth from `/` — nginx