more docs update

Author: ndbroadbent

DOCS_REVIEW.md

@@ -0,0 +1,36 @@
+# Docs Review (2026-01-29)
+
+This document tracks documentation mismatches found during the docs site audit and the fixes applied.
+
+## Resolved
+
+- CLI usage drift (removed `rack-gateway convox` wrapper; updated commands and flags).
+- Native Convox CLI examples now include the required `/api/v1/rack-proxy` base path.
+- API endpoint reference updated to match `internal/gateway/routes` and `/openapi.json`.
+- Removed references to non-existent `/api/v1/health/ready` endpoint.
+- CLI auth flow corrected (gateway callback + CLI polling).
+- Session cookie name updated to `session_token`.
+- CLI env vars corrected to `RACK_GATEWAY_RACK`, `RACK_GATEWAY_URL`, `RACK_GATEWAY_API_TOKEN`.
+- RBAC role list updated to include `cicd` and correct permission strings.
+- Environment variable reference updated with missing keys and correct setting names.
+- Docker and database docs updated to use `rack-gateway-api` and correct schema/table names.
+- Dev docs updated with correct OpenAPI artifact locations and codegen paths.
+- Monitoring docs corrected (audit logs are JSON; general logs are text).
+- `docs/README.md` replaced with real docs site overview.
+- Broken Convox reference link fixed by removing stale reference and pointing to current docs.
+- Web UI docs updated to match actual navigation and capabilities:
+  - Rack overview instead of “dashboard”.
+  - Users, API tokens, audit logs, settings pages reflect real columns and actions.
+  - Global settings reflect actual cards (MFA, destructive actions, session timeout, deploy approvals, VCS/CI defaults).
+- API token docs updated (format `rgw_`, permissions model, CLI env vars, UI columns).
+- MFA docs updated to match Account Security UI, backup code behavior, trusted device controls, and CLI usage.
+- Slack integration docs updated to use real audit action names (underscores) and deploy-approval alert config.
+- Deploy approvals docs updated:
+  - CircleCI example uses `rack-gateway deploy` and correct app settings location.
+  - Workflow doc uses rack-gateway commands for build/promote.
+- Deploy approvals workflow audit trail and approval window env var corrected.
+- GitHub integration docs updated with correct setting keys and PR comment behavior.
+
+## Remaining
+
+- None identified in this pass.

README.md

@@ -48,7 +48,7 @@ for managing multiple racks, monitoring and alerts, workflows for CI/CD, etc.
 
 - **[docs/DEPLOY.md](docs/DEPLOY.md)** - Production deployment guide
 - **[docs/CONFIGURATION.md](docs/CONFIGURATION.md)** - All environment variables and options
-- **[docs/CONVOX_REFERENCE.md](docs/CONVOX_REFERENCE.md)** - How Convox works
+- **[docs/legacy/CONVOX_REFERENCE.md](docs/legacy/CONVOX_REFERENCE.md)** - How Convox works
 
 ## Features
 
@@ -93,9 +93,9 @@ task dev
 # Login (opens mock OAuth in browser)
 ./bin/rack-gateway login staging http://localhost:8447
 
-# Run convox commands through the gateway
-./bin/rack-gateway convox apps
-./bin/rack-gateway convox ps
+# Run Convox commands through the gateway
+./bin/rack-gateway apps
+./bin/rack-gateway ps
 ```
 
 ### Prerequisites
@@ -182,29 +182,29 @@ The gateway acts as a transparent proxy that speaks the Convox API protocol. It
 
 ```bash
 # For CI/CD with API token
-export RACK_URL="https://convox:<api-token>@gateway.example.com"
+export RACK_URL="https://convox:<api-token>@gateway.example.com/api/v1/rack-proxy"
 convox apps  # Uses standard convox CLI directly
 
 # For developers with session token
-export RACK_URL="https://convox:<session-token>@gateway.example.com"
+export RACK_URL="https://convox:<session-token>@gateway.example.com/api/v1/rack-proxy"
 convox apps  # Uses standard convox CLI directly
 ```
 
 #### Option 2: rack-gateway CLI Wrapper (Convenience)
 
 ```bash
-# Use our wrapper for easier multi-rack management
+# Use our CLI for easier multi-rack management
 rack-gateway login staging https://gateway.example.com
-rack-gateway convox apps  # Automatically sets RACK_URL with stored token
+rack-gateway apps  # Automatically proxies via the gateway
 
 # Set up convenient shell alias
-alias cx="rack-gateway convox"
-cx apps
-cx ps
-cx deploy
+alias cg="rack-gateway"
+cg apps
+cg ps
+cg deploy
 ```
 
-The `rack-gateway` CLI wrapper is optional - it just provides:
+The `rack-gateway` CLI is optional if you prefer the native Convox CLI. It provides:
 
 - Automatic token management
 - Multi-rack configuration
@@ -225,16 +225,16 @@ rack-gateway login staging https://gateway.example.com
 ### Running Convox Commands
 
 ```bash
-# All convox commands go through "rack-gateway convox"
-rack-gateway convox apps
-rack-gateway convox ps
-rack-gateway convox deploy
-
-# With the cx alias:
-cx apps
-cx ps
-cx deploy
-cx logs -f
+# Convox commands are available directly
+rack-gateway apps
+rack-gateway ps
+rack-gateway deploy
+
+# With the cg alias:
+cg apps
+cg ps
+cg deploy
+cg logs -f
 ```
 
 ### Managing Racks
@@ -259,8 +259,8 @@ cg switch eu-west
 
 The CLI determines which rack to use in this order:
 
-1. `--rack` flag: `rack-gateway --rack production convox apps`
-2. Environment variable: `RACK_GATEWAY_RACK=production cx apps`
+1. `--rack` flag: `rack-gateway --rack production apps`
+2. Environment variable: `RACK_GATEWAY_RACK=production rack-gateway apps`
 3. Current rack stored in `~/.config/rack-gateway/config.json`
 
 ### Generate shell completions:
@@ -302,6 +302,7 @@ The CLI stores its configuration separately:
 - **ops**: Restart apps, view env (via releases), manage processes
 - **deployer**: Full deployment permissions (builds/releases), non-destructive
 - **admin**: Complete access to all operations
+- **cicd**: Automation tokens only (not assignable to human users)
 
 ### Permissions
 

docs/README.md

@@ -1,49 +1,34 @@
-# Starlight Starter Kit: Basics
+# Rack Gateway Docs
 
-[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+This directory contains the Astro/Starlight documentation site for Rack Gateway.
 
-```
-bun create astro@latest -- --template starlight
-```
+## Content
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+- Docs live in `docs/src/content/docs/`
+- Static assets live in `docs/public/`
 
-## 🚀 Project Structure
+## Development
 
-Inside of your Astro + Starlight project, you'll see the following folders and files:
+From the repository root:
 
+```bash
+cd docs
+bun install
+bun dev
 ```
-.
-├── public/
-├── src/
-│   ├── assets/
-│   ├── content/
-│   │   └── docs/
-│   └── content.config.ts
-├── astro.config.mjs
-├── package.json
-└── tsconfig.json
-```
-
-Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
 
-Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+The dev server prints the local URL on startup.
 
-Static assets, like favicons, can be placed in the `public/` directory.
+## Build
 
-## 🧞 Commands
-
-All commands are run from the root of the project, from a terminal:
-
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `bun install`             | Installs dependencies                            |
-| `bun dev`             | Starts local dev server at `localhost:4321`      |
-| `bun build`           | Build your production site to `./dist/`          |
-| `bun preview`         | Preview your build locally, before deploying     |
-| `bun astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `bun astro -- --help` | Get help using the Astro CLI                     |
+```bash
+cd docs
+bun build
+```
 
-## 👀 Want to learn more?
+## Preview
 
-Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+```bash
+cd docs
+bun preview
+```

docs/src/content/docs/concepts/rbac-principles.mdx

@@ -54,10 +54,10 @@ Specific actions that can be performed. Rack Gateway uses a hierarchical permiss
 
 ```
 convox:*                    # All Convox permissions
-convox:apps:*               # All app-related permissions
-convox:apps:list            # List applications
-convox:apps:create          # Create applications
-convox:releases:promote     # Promote releases (deploy)
+convox:app:*                # All app-related permissions
+convox:app:list             # List applications
+convox:app:create           # Create applications
+convox:release:promote      # Promote releases (deploy)
 ```
 
 ### Role-Permission Mapping
@@ -183,13 +183,13 @@ What actions can be performed on each resource?
 Combine resources and operations:
 
 ```
-apps:list
-apps:create
-apps:delete
-deploys:create
-deploys:promote
-logs:view
-users:create
+convox:app:list
+convox:app:create
+convox:app:delete
+convox:release:create
+convox:release:promote
+convox:log:read
+gateway:user:create
 ```
 
 ### Step 4: Define Roles
@@ -198,22 +198,23 @@ Group permissions by job function:
 
 ```yaml
 viewer:
-  - apps:list
-  - logs:view
+  - convox:app:list
+  - convox:log:read
 
 developer:
-  - apps:list
-  - apps:update
-  - logs:view
-  - exec:run
+  - convox:app:list
+  - convox:app:update
+  - convox:log:read
+  - convox:process:exec
 
 operator:
-  - apps:*
-  - deploys:*
-  - logs:*
+  - convox:app:*
+  - convox:release:*
+  - convox:log:*
 
 admin:
-  - *:*
+  - convox:*:*
+  - gateway:*:*
 ```
 
 ### Step 5: Assign Roles to Users
@@ -235,27 +236,27 @@ users:
 | Role | Purpose | Key Permissions |
 |------|---------|-----------------|
 | **Admin** | Full system access | All permissions including user management |
-| **Operator** | Production operations | Deploy, scale, environment management |
-| **Developer** | Development work | Run commands, view logs, limited writes |
+| **Deployer** | Production operations | Deploy, scale, environment management |
+| **Ops** | Operational work | Run commands, view logs, manage processes |
 | **Viewer** | Read-only access | View apps, logs, status |
 
 ### Permission Structure
 
 Rack Gateway uses a hierarchical permission system:
 
 ```
-gateway:*              # All gateway permissions
-gateway:admin:*        # Admin functions
-gateway:admin:users    # User management
-gateway:admin:tokens   # API token management
-gateway:admin:settings # Settings management
-
-convox:*               # All Convox permissions
-convox:apps:*          # App management
-convox:builds:*        # Build operations
-convox:releases:*      # Release/deploy operations
-convox:env:*           # Environment variables
-convox:exec:*          # Command execution
+gateway:*                     # All gateway permissions
+gateway:user:*                # User management
+gateway:api_token:*           # API token management
+gateway:deploy_approval_request:* # Deploy approvals
+gateway:setting:*             # Settings (individual)
+
+convox:*                      # All Convox permissions
+convox:app:*                  # App management
+convox:build:*                # Build operations
+convox:release:*              # Release/deploy operations
+convox:env:*                  # Environment variables
+convox:process:*              # Process operations
 ```
 
 ### Role Assignment