more tidy up and added docs for secret management

Author: ndbroadbent

README.md

@@ -212,14 +212,10 @@ See docs/CONFIGURATION.md for the full list of environment variables and configu
 
 ### Database
 
-The gateway uses a SQLite database to store users, API tokens, and audit logs:
+The gateway uses Postgres to store users, API tokens, and audit logs. Set a connection URL via `DATABASE_URL` (or equivalent `PG*` vars):
 
 ```bash
-# Default location
-Postgres is required; no SQLite support.
-
-# Override with environment variable
-DATABASE_URL=postgres://user:pass@host:5432/db?sslmode=require
+DATABASE_URL=postgres://user:pass@host:5432/dbname?sslmode=require
 ```
 
 The database is automatically initialized on first run with an admin user from the first Google OAuth login.
@@ -395,7 +391,7 @@ For issues or questions:
 
 ### Retention and scheduled cleanup
 
-Audit events are stored in SQLite for the UI and also emitted to stdout in structured JSON for CloudWatch. To keep the local DB small:
+Audit events are stored in Postgres and also emitted to stdout in structured JSON for CloudWatch. To keep the DB lean:
 
 - Environment-based cleanup at boot: set `AUDIT_LOG_RETENTION_DAYS` to purge old rows during startup.
 - Scheduled cleanup command (for Convox timers):

docs/CONFIGURATION.md

@@ -54,9 +54,8 @@ If you’re deploying to production, read this alongside [DEPLOY.md](DEPLOY.md).
 
 ## Database and Auditing
 
-Postgres is required; set `DATABASE_URL` or `PG*` variables.
+Postgres is required; set `DATABASE_URL` (or `PG*` variables like `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`).
 
-- SQLite database path for users, tokens, and audit logs.
 - `AUDIT_LOG_RETENTION_DAYS` (optional)
   - If set, the server purges audit rows older than N days at startup.
   - Also used by the `convox-gateway audit-cleanup --days N` command (see [DEPLOY.md](DEPLOY.md)).

docs/SECRETS.md

@@ -0,0 +1,65 @@
+# Managing Secrets and Env Vars
+
+This gateway enforces secret masking at the proxy layer for every client (web UI, Convox CLI, scripts). Masking is always applied by default. To intentionally view plaintext values, you must be authorized and explicitly request secrets via the gateway.
+
+## How masking works
+
+- The gateway masks values for variables commonly treated as secrets (e.g., keys, passwords, tokens). It also respects an allowlist of additional secret keys via `CONVOX_SECRET_ENV_VARS` (comma‑separated key names).
+- To see unmasked values, your account must have the `secrets:view` permission (assigned via RBAC), and you must pass `--secrets` to the CLI.
+
+## Use `convox-gateway env` to request plaintext
+
+The `convox-gateway` CLI exposes an `env` command that talks to the gateway API. Masking is applied by default; pass `--secrets` to request plaintext if you have permission.
+
+Examples below assume you have logged in and selected a rack with:
+
+```bash
+convox-gateway login <rack> <gateway-origin>
+```
+
+### List env vars (masked by default)
+
+```bash
+# Masked output
+convox-gateway env -a myapp
+
+# Unmasked if you have permission
+convox-gateway env --secrets -a myapp
+```
+
+### Get a single key
+
+```bash
+# Masked by default
+convox-gateway env get DATABASE_URL -a myapp
+
+# Unmasked (requires secrets:view permission)
+convox-gateway env get DATABASE_URL --secrets -a myapp
+```
+
+### Set / unset env vars
+
+`convox-gateway` provides aliases that delegate to the Convox CLI for writes:
+
+```bash
+# Set (delegates to: convox env set)
+convox-gateway env set FOO=bar OTHER=baz -a myapp --promote
+
+# Unset (delegates to: convox env unset)
+convox-gateway env unset FOO -a myapp --promote
+```
+
+Notes:
+- Writes occur via the Convox CLI, so they follow Convox semantics (release creation, optional `--promote`, etc.).
+- Reads happen via the gateway, with masking applied unless `--secrets` is provided and authorized.
+
+## Convox CLI behavior
+
+- `convox env` (Convox CLI through the gateway): returns masked values by default, with masking enforced by the gateway. The native Convox CLI does not provide an "unmask" option via the gateway.
+- To view plaintext values (when authorized), use `convox-gateway env --secrets`.
+
+## Tips
+
+- Avoid pasting unmasked secrets into terminals or logs. Prefer masked reads unless you explicitly need plaintext (`--secrets`).
+- For scripting, parse JSON from the gateway API directly if needed; the CLI prints key=value lines for quick inspection.
+- Add extra sensitive keys to `CONVOX_SECRET_ENV_VARS` to ensure they are masked by default.