From e46f1b10759af6cb41c163938453d81d8ae3ec31 Mon Sep 17 00:00:00 2001
From: vNodesV <claude@vnodes.cloud>
Date: Fri, 19 Jun 2026 02:09:56 +0000
Subject: [PATCH] docs: fix vprox command hierarchy to nest under vops

vProx/vprox was documented as the top-level command in several places
(CLI_FLAGS_GUIDE.md, README.md, MODULES.md, INSTALLATION.md,
docs/UPGRADE.md) when it's actually a subcommand of vops
(vops vprox <start|stop|restart|status|view>). Restructured docs to
reflect the correct hierarchy and clearly separated the advanced
standalone vProx binary's flag set (only relevant for dev/diagnostics
via cmd/vprox directly) from the vops-wrapped service commands.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLI_FLAGS_GUIDE.md | 418 +++++++++++++--------------------------------
 INSTALLATION.md    |  27 +--
 MODULES.md         |  85 +++++----
 README.md          |  37 ++--
 docs/UPGRADE.md    |   2 +-
 5 files changed, 207 insertions(+), 362 deletions(-)

diff --git a/CLI_FLAGS_GUIDE.md b/CLI_FLAGS_GUIDE.md
index 55bab46..dc51cc6 100644
--- a/CLI_FLAGS_GUIDE.md
+++ b/CLI_FLAGS_GUIDE.md
@@ -1,35 +1,29 @@
-# vProx CLI Flags Guide
+# vOps CLI Flags Guide
 
-Authoritative guide for all vProx commands and command-line flags.
+Authoritative guide for the `vops` command-line interface and its embedded `vprox` subcommand.
 
 ## Commands
 
-### `vProx start`
-Start the proxy server in the foreground. Logs to stdout and `main.log`.
+### `vops start`
+Start vOps server (foreground). Logs to stdout.
 
-### `vProx start -d` / `vProx start --daemon`
-Start via systemd service (`sudo service vProx start`). Requires the sudoers rule and unit file created by `make install`.
+### `vops start -d` / `vops start --daemon`
+Start via systemd service (`sudo service vOps start`).
 
-### `vProx start --with-vops`
-Start the proxy server and vOps log analyzer in integrated mode (same process, coordinated shutdown). vOps listens on the port configured in `config/vops/vops.toml`.
+### `vops stop`
+Stop vOps service (`sudo service vOps stop`).
 
-### `vProx stop`
-Stop the running service (`sudo service vProx stop`).
+### `vops restart`
+Restart vOps service (`sudo service vOps restart`).
 
-### `vProx restart`
-Restart the running service (`sudo service vProx restart`).
+### `vops ingest`
+Run one-shot archive ingest and exit.
 
-### `vProx completion <shell>`
-Generate shell completion script for the specified shell. Supported shells: `bash`, `zsh`, `fish`.
+### `vops status`
+Show database stats and exit.
 
-```bash
-vprox completion bash   >> ~/.bash_completion
-vprox completion zsh    >> ~/.zshrc
-vprox completion fish   > ~/.config/fish/completions/vprox.fish
-```
-
-### `vProx vops <subcommand>`
-Manage the vOps log analyzer. See [vOps CLI Reference](#vops-cli-reference) below.
+### `vops vprox <subcommand>`
+Manage the embedded vProx proxy server. See [vprox subcommand reference](#vprox-subcommand-reference) below.
 
 ---
 
@@ -37,329 +31,163 @@ Manage the vOps log analyzer. See [vOps CLI Reference](#vops-cli-reference) belo
 
 Use long flags with a double dash:
 
-- `vProx --help`
-- `vProx --validate`
-- `vProx --dry-run --verbose`
+- `vops --help`
+- `vops --validate`
+- `vops --dry-run --verbose`
 
 > Compatibility note: Go's flag parser still accepts single-dash form (`-flag`), but project docs standardize on `--flag`.
 
 ---
 
-## Configuration paths
-
-### `--home string`
-Override runtime home (`VPROX_HOME`), defaulting to `~/.vOps` if unset.
-
-Use when:
-- running isolated instances
-- testing with disposable environments
-
-Examples:
-- `vProx --home /srv/vprox`
-- `vProx --home /tmp/vprox-dev`
-
-### `--config string`
-Override config directory (contains `ports.toml`; may also include legacy chain TOMLs).
-
-- relative paths resolve under `--home`
-- absolute paths are used as-is
-
-Examples:
-- `vProx --config /etc/vprox/config`
-- `vProx --config config-alt`
-
-### `--chains string`
-Override chains directory (primary location for chain `*.toml` files).
-
-- relative paths resolve under `--home`
-- absolute paths are used as-is
+## Global flags
 
-Examples:
-- `vProx --chains /etc/vprox/chains`
-- `vProx --chains chains-staging`
-
-### `--log-file string`
-Override main log file path.
-
-- default: `<home>/data/logs/main.log`
-- relative paths resolve under `<home>/data/logs`
-
-Examples:
-- `vProx --log-file main-dev.log`
-- `vProx --log-file /var/log/vprox/main.log`
-
-### `--addr string`
-HTTP listen address.
-
-- default: `:3000`
-- env fallback: `VPROX_ADDR`
-- CLI flag has priority over env
+| Flag | Default | Description |
+|---|---|---|
+| `--home PATH` | `$VOPS_HOME` or `~/.vOps` | Override vOps home directory |
+| `--config PATH` | — | Override config file path |
+| `-p`, `--port PORT` | from `vops.toml` | Override web server listen port |
+| `-q`, `--quiet` | false | Suppress non-essential output |
+| `-v`, `--verbose` | false | Verbose log output |
+| `--version` | — | Print version and exit |
+| `-h`, `--help` | — | Print usage |
 
 Examples:
-- `vProx --addr :8080`
-- `vProx --addr 0.0.0.0:3000`
+- `vops --home /srv/vops`
+- `vops --home /tmp/vops-dev`
 
 ---
 
-## Startup / run modes
-
-### `--help`
-Show usage and available flags.
+## One-shot flags
 
-### `--version`
-Print version and exit.
-
-### `--with-vops`
-Start vOps log analyzer alongside the proxy in integrated mode. Both servers share the same process and shut down together. vOps listens on the port in `config/vops/vops.toml` (default `:8889`).
-
-Example:
-- `vProx start --with-vops`
-
-### `--validate`
-Load and validate configuration, then exit.
-
-Checks include:
-- required `ports.toml`
-- chain host/IP validity
-- service/port compatibility
-- routing-related config constraints
-
-Use when:
-- preflight checks in CI/CD
-- verifying config before restart
-
-### `--info`
-Load configuration, print runtime summary, and exit.
-
-Includes:
-- resolved directories
-- loaded chains
-- default ports
-- extra details when combined with `--verbose`
-
-### `--dry-run`
-Load everything but do not start server.
-
-Prints effective runtime summary, including:
-- listen address
-- chain count
-- effective limiter settings
-- auto-quarantine status
-- backup enabled/disabled status
-
-Use when:
-- validating startup behavior safely
+| Flag | Description |
+|---|---|
+| `-A`, `--list-archives` | List ingested archives with event counts |
+| `-a`, `--list-accounts` | List IP accounts (top 50, by last_seen) |
+| `-t`, `--list-threats` | List flagged IPs sorted by threat score desc |
+| `-e`, `--enrich <ip>` | Enrich an IP via all intel sources and exit |
+| `-x`, `--purge-cache <ip\|all>` | Clear intel cache (one IP or all) and exit |
+| `-V`, `--validate` | Validate `vops.toml` and exit |
+| `-i`, `--info` | Show resolved config summary and exit |
+| `-n`, `--dry-run` | Load config + open DB, verify, exit without starting |
 
 ---
 
-## Rate limiting overrides
-
-These CLI values override env values for this run.
-
-### `--rps float`
-Override default requests-per-second.
-
-- env: `VPROX_RPS`
-- built-in default: `25`
-- applied when value is `> 0`
-
-Example:
-- `vProx --rps 50`
-
-### `--burst int`
-Override default burst capacity.
-
-- env: `VPROX_BURST`
-- built-in default: `100`
-- applied when value is `> 0`
-
-Example:
-- `vProx --burst 250`
-
-### `--disable-auto`
-Disable auto-quarantine behavior.
-
-Equivalent intent to `VPROX_AUTO_ENABLED=false`, with CLI taking precedence.
-
-### `--auto-rps float`
-Override auto-quarantine penalty RPS.
-
-- env: `VPROX_AUTO_RPS`
-- built-in default: `1`
-- applied when value is `> 0`
-
-Example:
-- `vProx --auto-rps 0.5`
-
-### `--auto-burst int`
-Override auto-quarantine penalty burst.
+## Runtime flags (`start`)
 
-- env: `VPROX_AUTO_BURST`
-- built-in default: `1`
-- applied when value is `> 0`
-
-Example:
-- `vProx --auto-burst 2`
+| Flag | Description |
+|---|---|
+| `-d`, `--daemon` | Start as background daemon (`sudo service vOps start`) |
+| `-W`, `--no-watch` | Disable archive file watcher |
+| `-E`, `--no-enrich` | Disable intel auto-enrichment worker |
+| `-w`, `--watch-interval N` | Override `watch_interval_sec` |
 
 ---
 
-## Backup controls
-
-### `--new-backup`
-Run one backup cycle and exit (no proxy server start).
-
-Examples:
-- `vProx --new-backup`
-- `vProx --new-backup --reset_count`
-
-### `--list-backup`
-List existing backup archives and exit.
-
-### `--backup-status`
-Show backup scheduler status (automation state, next ETA, archive count) and exit.
+## Practical command sets
 
-### `--disable-backup`
-Disable automatic backup loop at startup.
+### Service management
+- `vops start` — foreground
+- `vops start -d` — daemon (systemd service)
+- `vops stop` — stop service
+- `vops restart` — restart service
 
-Does not affect manual one-shot backups via `--new-backup`.
+### Pre-deploy check
+- `vops --validate`
+- `vops --dry-run --verbose`
 
-### `--reset_count`
-Reset persisted access counters before backup execution.
+### Inspect resolved runtime
+- `vops --info --verbose`
 
-### `--reset-count`
-Alias for `--reset_count`.
+### Intelligence
+```bash
+vops --enrich 1.2.3.4       # run VT + AbuseIPDB + Shodan on IP
+vops --purge-cache 1.2.3.4  # clear cached score for IP
+vops --list-threats         # print IPs with score >= 50
+```
 
 ---
 
-## Verbosity / diagnostics
-
-### `--verbose`
-Enable extra startup diagnostics and override logs.
-
-Great with:
-- `--info`
-- `--dry-run`
+## vprox subcommand reference {#vprox-subcommand-reference}
 
-### `--quiet`
-Flag is present, but current implementation still logs to configured log file.
+`vprox` manages the embedded reverse proxy and is invoked as a subcommand of `vops` — there is no standalone top-level `vprox` command in normal operation.
 
-Treat as reserved/minimal-effect in the current build.
-
----
+### Commands
 
-## Precedence rules
+| Command | Description |
+|---|---|
+| `vops vprox start` | Start vProx in the foreground (blocks until Ctrl-C) |
+| `vops vprox start -d` | Start vProx as a background systemd daemon |
+| `vops vprox stop` | Stop the vProx systemd service |
+| `vops vprox restart` | Restart the vProx systemd service |
+| `vops vprox status` | Show service state, uptime, and config paths |
+| `vops vprox view` | Follow vProx service logs (`journalctl -u vProx -f`) |
 
-For overlapping settings:
+Global flags apply: `--home`, `--verbose`, `--quiet`.
 
-1. CLI flags (`--...`)
-2. Environment variables
-3. Built-in defaults / config-derived values
+### Practical command sets
 
-Example:
-- `VPROX_RPS=30 vProx --rps 100` → effective default RPS is `100`
+```bash
+vops vprox start -d    # daemon
+vops vprox stop        # stop
+vops vprox restart     # restart
+vops vprox status      # show stats
+vops vprox view        # tail logs
+```
 
 ---
 
-## Practical command sets
-
-### Service management
-- `vProx start` — foreground
-- `vProx start -d` — daemon (systemd service)
-- `vProx stop` — stop service
-- `vProx restart` — restart service
+## Advanced: standalone vProx binary (dev/diagnostics only)
 
-### Pre-deploy check
-- `vProx --validate`
-- `vProx --dry-run --verbose`
+The proxy is also buildable as its own binary (`make build-vprox` → `.build/vProx`, `go run ./cmd/vprox`) for local development and diagnostics outside the systemd-managed deployment. It exposes a much larger flag set than the `vops vprox` wrapper above — useful for one-off config validation, rate-limit overrides, and manual backups without touching the production service.
 
-### Inspect resolved runtime
-- `vProx --info --verbose`
+> Production deployments should prefer `vops vprox <subcommand>` for day-to-day service control. The flags below only apply when invoking `./cmd/vprox`/`.build/vProx` directly.
 
-### Temporary hardening
-- `vProx --rps 10 --burst 20 --auto-rps 0.5 --auto-burst 1`
+### Configuration paths
 
-### Backup operations
-- `vProx --new-backup` — run one backup cycle
-- `vProx --new-backup --reset_count` — backup + reset counters
-- `vProx --list-backup` — list archives
-- `vProx --backup-status` — show scheduler status
+- `--home string` — override runtime home (`VPROX_HOME`), defaulting to `~/.vOps` if unset
+- `--config string` — override config directory (relative paths resolve under `--home`)
+- `--chains string` — override chains directory (relative paths resolve under `--home`)
+- `--log-file string` — override main log file path (default `<home>/data/logs/main.log`)
+- `--addr string` — HTTP listen address (default `:3000`, env fallback `VPROX_ADDR`)
 
----
+### Startup / run modes
 
-## vOps CLI Reference {#vops-cli-reference}
+- `--help` — show usage and available flags
+- `--version` — print version and exit
+- `--with-vops` — start vOps log analyzer alongside the proxy in integrated mode (same process, coordinated shutdown)
+- `--validate` — load and validate configuration, then exit
+- `--info` — load configuration, print runtime summary, and exit
+- `--dry-run` — load everything but do not start server
 
-vOps is the companion log-analyzer (renamed from vLog in v1.4.0). It is integrated as `vprox vops` subcommand.
+### Rate limiting overrides
 
-### Commands
+CLI values override env values for this run. Precedence: CLI flags > environment variables > built-in defaults.
 
-| Command | Description |
-|---|---|
-| `vprox vops start` | Start vOps web server (foreground, default `:8889`) |
-| `vprox vops start -d` | Start as background service (`sudo service vOps start`) |
-| `vprox vops stop` | Stop vOps service (`sudo service vOps stop`) |
-| `vprox vops restart` | Restart vOps service (`sudo service vOps restart`) |
-| `vprox vops ingest` | One-shot: scan archives, ingest new entries, exit |
-| `vprox vops status` | Print database stats and exit |
-| `vprox vops accounts` | List all IP accounts as JSON |
-| `vprox vops threats` | List flagged IPs (score ≥ 50) |
-| `vprox vops cache` | Manage intel cache (purge by IP or all) |
-
-### Flags (all commands)
+- `--rps float` — override default requests-per-second (env `VPROX_RPS`, default `25`)
+- `--burst int` — override default burst capacity (env `VPROX_BURST`, default `100`)
+- `--disable-auto` — disable auto-quarantine behavior
+- `--auto-rps float` — override auto-quarantine penalty RPS (env `VPROX_AUTO_RPS`, default `1`)
+- `--auto-burst int` — override auto-quarantine penalty burst (env `VPROX_AUTO_BURST`, default `1`)
 
-| Flag | Default | Description |
-|---|---|---|
-| `--home PATH` | `$VPROX_HOME` or `~/.vOps` | Override vProx home directory |
-| `--port PORT` | from `vops.toml` | Override web server listen port |
-| `--quiet` | false | Suppress non-essential output |
-| `--version` | — | Print version and exit |
-| `-h`, `--help` | — | Print usage |
+Example: `VPROX_RPS=30 ./.build/vProx start --rps 100` → effective RPS is `100`.
 
-### Flags (start only)
+### Backup controls
 
-| Flag | Default | Description |
-|---|---|---|
-| `--no-watch` | false | Disable background FS watcher (no auto-ingest) |
-| `--no-enrich` | false | Disable auto-enrichment on new IPs |
-| `--watch-interval DURATION` | `30s` | FS watcher poll interval |
-
-### Flags (one-shot / diagnostic)
-
-| Flag | Description |
-|---|---|
-| `--list-archives` | List all ingested archive files |
-| `--list-accounts` | Print all IP accounts as JSON |
-| `--list-threats` | Print flagged IPs (score ≥ 50) |
-| `--enrich IP` | Run threat intelligence on a single IP and print result |
-| `--purge-cache IP\|all` | Evict cached intel for one IP or all IPs |
-| `--validate` | Validate `vops.toml` config and exit |
-| `--info` | Print resolved config and exit |
-| `--dry-run` | Validate + print without starting server |
-
-### Priority order
+- `--new-backup` — run one backup cycle and exit (no proxy server start)
+- `--list-backup` — list existing backup archives and exit
+- `--backup-status` — show backup scheduler status (automation state, next ETA, archive count) and exit
+- `--disable-backup` — disable automatic backup loop at startup (does not affect manual `--new-backup`)
+- `--reset_count` / `--reset-count` — reset persisted access counters before backup execution
 
-1. CLI flags
-2. `$VPROX_HOME/config/vops/vops.toml`
-3. Built-in defaults
+### Shell completion
 
-### Practical command sets
-
-#### Service management
 ```bash
-vprox vops start -d    # daemon
-vprox vops stop        # stop
-vprox vops restart     # restart
-vprox vops status      # show stats
+./.build/vProx completion bash   >> ~/.bash_completion
+./.build/vProx completion zsh    >> ~/.zshrc
+./.build/vProx completion fish   > ~/.config/fish/completions/vprox.fish
 ```
 
-#### Manual ingest
-```bash
-vprox vops ingest      # process all pending archives
-vprox vops ingest --home /custom/path
-```
+### Verbosity / diagnostics
 
-#### Intelligence
-```bash
-vprox vops --enrich 1.2.3.4       # run VT + AbuseIPDB + Shodan on IP
-vprox vops --purge-cache 1.2.3.4  # clear cached score for IP
-vprox vops --list-threats          # print IPs with score ≥ 50
-```
+- `--verbose` — enable extra startup diagnostics and override logs (pairs well with `--info` / `--dry-run`)
+- `--quiet` — flag is present, but current implementation still logs to configured log file; treat as reserved/minimal-effect in the current build
diff --git a/INSTALLATION.md b/INSTALLATION.md
index 445bec3..5a5dac1 100644
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -156,7 +156,7 @@ Override the base path:
 export VPROX_HOME=/opt/vprox
 
 # CLI flag (overrides env var):
-vProx --home /opt/vprox
+vops vprox --home /opt/vprox
 ```
 
 ---
@@ -296,12 +296,12 @@ Follow live logs in CosmosSDK-style line format:
 journalctl -u vProx.service -f --output=cat
 ```
 
-Start / stop / restart (via vProx CLI — passwordless with sudoers rule):
+Start / stop / restart (via the `vops vprox` CLI — passwordless with sudoers rule):
 
 ```bash
-vProx start -d     # start as daemon
-vProx stop         # stop the service
-vProx restart      # restart the service
+vops vprox start -d     # start as daemon
+vops vprox stop         # stop the service
+vops vprox restart      # restart the service
 ```
 
 Or directly with systemctl:
@@ -324,13 +324,20 @@ go run ./cmd/vprox --info      # Print resolved config summary
 go run ./cmd/vprox --dry-run   # Load config without starting server
 ```
 
-**After install:**
+**After install (recommended — via `vops`):**
+
+```bash
+vops vprox start                # Start server foreground (default :3000)
+vops vprox start -d             # Start as daemon (systemd service)
+vops vprox stop                 # Stop the service
+vops vprox restart              # Restart the service
+vops vprox status               # Show service state and basic stats
+vops vprox view                 # Tail vProx service logs
+```
+
+**Advanced flags (standalone `vProx` binary only — `.build/vProx` or `go run ./cmd/vprox`):**
 
 ```bash
-vProx start                    # Start server foreground (default :3000)
-vProx start -d                 # Start as daemon (systemd service)
-vProx stop                     # Stop the service
-vProx restart                  # Restart the service
 vProx --addr :4000             # Override listen address
 vProx --validate               # Validate config files
 vProx --info --verbose         # Full runtime/config summary
diff --git a/MODULES.md b/MODULES.md
index cb28a5e..6e82399 100644
--- a/MODULES.md
+++ b/MODULES.md
@@ -20,7 +20,7 @@ By default, vProx runs out of:
 Override base path with:
 
 - `VPROX_HOME=/custom/path`
-- CLI: `vProx --home /custom/path`
+- CLI: `vops vprox --home /custom/path` (or `./.build/vProx --home /custom/path` standalone)
 
 ### Chain configs
 
@@ -79,18 +79,18 @@ api      = 1317
 
 ### Run
 
-- `vProx start` — start server foreground (default `:3000`)
-- `vProx start -d` — start as daemon (systemd service)
-- `vProx stop` — stop the service
-- `vProx restart` — restart the service
-- `vProx --addr :4000` — override listen address
+- `vops vprox start` — start server foreground (default `:3000`)
+- `vops vprox start -d` — start as daemon (systemd service)
+- `vops vprox stop` — stop the service
+- `vops vprox restart` — restart the service
+- `./.build/vProx --addr :4000` — override listen address (standalone binary; see [Advanced standalone vProx binary](#advanced-standalone-vprox-binary))
 
 ### Manual backup
 
-- `vProx --new-backup`
-- `vProx --new-backup --reset_count` (also accepts `--reset-count`)
-- `vProx --list-backup` — list existing archives
-- `vProx --backup-status` — show scheduler status
+- `./.build/vProx --new-backup`
+- `./.build/vProx --new-backup --reset_count` (also accepts `--reset-count`)
+- `./.build/vProx --list-backup` — list existing archives
+- `./.build/vProx --backup-status` — show scheduler status
 
 ---
 
@@ -208,11 +208,13 @@ If no database is found, geo enrichment is silently disabled. All proxy function
 
 ### Manual backup
 
+Manual backup flags are exposed by the standalone `vProx` binary (see [Advanced standalone vProx binary](./CLI_FLAGS_GUIDE.md#advanced-standalone-vprox-binary-devdiagnostics-only)), not the `vops vprox` wrapper:
+
 ```bash
-vProx --new-backup                # Run one backup cycle
-vProx --new-backup --reset_count  # Backup + reset access counters
-vProx --list-backup               # List existing archives
-vProx --backup-status             # Show scheduler status
+./.build/vProx --new-backup                # Run one backup cycle
+./.build/vProx --new-backup --reset_count  # Backup + reset access counters
+./.build/vProx --list-backup               # List existing archives
+./.build/vProx --backup-status             # Show scheduler status
 ```
 
 ### Automated backups
@@ -270,7 +272,7 @@ $HOME/.vOps/data/logs/archives/backup.YYYYMMDD_HHMMSS.tar.gz
 Source access counters (`src_count`) are persisted at `$HOME/.vOps/data/access-counts.json`. They survive restarts and backup cycles. Reset only when explicitly requested:
 
 ```bash
-vProx backup --reset_count    # or --reset-count
+./.build/vProx --new-backup --reset_count    # or --reset-count
 ```
 
 ---
@@ -342,15 +344,22 @@ make clean         # Remove .build/
 
 For the full flag reference with examples, see [`CLI_FLAGS_GUIDE.md`](./CLI_FLAGS_GUIDE.md).
 
-**Most common flags:**
+**Service control via `vops` (recommended for normal operation):**
+
+```bash
+vops vprox start                      # Start server foreground (default :3000)
+vops vprox start -d                   # Start as daemon (systemd service)
+vops vprox stop                       # Stop the service
+vops vprox restart                    # Restart the service
+vops vprox status                     # Show service state and basic stats
+vops vprox view                       # Tail vProx service logs
+```
+
+**Advanced standalone vProx binary (`./.build/vProx`, `go run ./cmd/vprox`) — dev/diagnostics only:**
 
 ```bash
 vProx --help                          # Built-in help
 vProx --version                       # Print version
-vProx start                           # Start server foreground (default :3000)
-vProx start -d                        # Start as daemon (systemd service)
-vProx stop                            # Stop the service
-vProx restart                         # Restart the service
 vProx --validate                      # Validate config and exit
 vProx --info --verbose                # Print resolved runtime/config summary
 vProx --dry-run                       # Load everything, don't start server
@@ -366,7 +375,7 @@ vProx --list-backup                   # List backup archives
 vProx --backup-status                 # Show scheduler status
 ```
 
-**Rate limit overrides (CLI, override .env):**
+**Rate limit overrides (standalone binary CLI, override .env):**
 
 ```bash
 vProx --rps 50              # Requests per second
@@ -420,7 +429,7 @@ absolute_links      = "auto" # auto | always | never
 - `cmd/vops/` — binary entry point
 - `internal/vops/` — packages (config, db, ingest, intel, web)
 
-**Binary**: `vops` (integrated via `vprox vops`) — standalone, mirrors vProx architecture (single binary, embedded HTTP server, Apache-proxied).
+**Binary**: `vops` — the primary CLI entry point (single binary, embedded HTTP server, Apache-proxied); `vprox` is its embedded subcommand (`vops vprox <start|stop|restart|status|view>`).
 
 **Database**: SQLite at `$VPROX_HOME/data/vops.db` via `modernc.org/sqlite` (pure Go, no CGO required).
 
@@ -430,15 +439,15 @@ absolute_links      = "auto" # auto | always | never
 
 | Command | Action |
 |---|---|
-| `vprox vops start` | Start vOps server (foreground) |
-| `vprox vops start -d` | Start as background daemon (`sudo service vOps start`) |
-| `vprox vops stop` | Stop vOps service (`sudo service vOps stop`) |
-| `vprox vops restart` | Restart vOps service (`sudo service vOps restart`) |
-| `vprox vops ingest` | One-shot archive ingest and exit |
-| `vprox vops status` | Show database stats and exit |
-| `vprox vops accounts` | List IP accounts as JSON |
-| `vprox vops threats` | List flagged IPs (score ≥ 50) |
-| `vprox vops cache` | Manage intel cache |
+| `vops start` | Start vOps server (foreground) |
+| `vops start -d` | Start as background daemon (`sudo service vOps start`) |
+| `vops stop` | Stop vOps service (`sudo service vOps stop`) |
+| `vops restart` | Restart vOps service (`sudo service vOps restart`) |
+| `vops ingest` | One-shot archive ingest and exit |
+| `vops status` | Show database stats and exit |
+| `vops -a` | List IP accounts as JSON |
+| `vops -t` | List flagged IPs (score ≥ 50) |
+| `vops -x <ip\|all>` | Manage intel cache (purge by IP or all) |
 
 **Runtime flags (start):** `--home`, `--port`, `--quiet`, `--no-watch`, `--no-enrich`, `--watch-interval`
 **One-shot flags:** `--list-archives`, `--list-accounts`, `--list-threats`, `--enrich <ip>`, `--purge-cache <ip|all>`, `--validate`, `--info`, `--dry-run`
@@ -640,13 +649,15 @@ exposed_services = true      # true = probe via chain.host; false = probe via la
 
 ### CLI Commands
 
+Fleet management is exposed by the standalone `vProx` binary's own `fleet` subcommand (`cmd/vprox`), not `vops vprox`:
+
 ```bash
-vprox fleet hosts          # List physical hosts from config/infra/
-vprox fleet vms            # List all registered VMs
-vprox fleet chains         # List chains registered in fleet SQLite state
-vprox fleet unregister <chain>   # Remove chain from fleet state (by chain_name)
-vprox fleet deploy --chain <name> --script <path>   # Dispatch script to VM via SSH
-vprox fleet update [--host <name>]   # Run apt upgrade on VM(s) via SSH
+./.build/vProx fleet hosts          # List physical hosts from config/infra/
+./.build/vProx fleet vms            # List all registered VMs
+./.build/vProx fleet chains         # List chains registered in fleet SQLite state
+./.build/vProx fleet unregister <chain>   # Remove chain from fleet state (by chain_name)
+./.build/vProx fleet deploy --chain <name> --script <path>   # Dispatch script to VM via SSH
+./.build/vProx fleet update [--host <name>]   # Run apt upgrade on VM(s) via SSH
 ```
 
 ### API Routes
diff --git a/README.md b/README.md
index 7a9b447..b70524e 100644
--- a/README.md
+++ b/README.md
@@ -67,15 +67,15 @@ A **React 18 + TypeScript SPA** for log analysis, threat intel, and fleet operat
 ```bash
 make install              # first-time setup: builds + installs vOps + vProx, config, services
 make upgrade              # later: rebuild + redeploy both binaries after a code change
-vprox vops start         # foreground server (default: :8889)
-vprox vops start -d      # start as background service
-vprox vops stop          # stop vOps service
-vprox vops restart       # restart vOps service
-vprox vops status        # show status and database stats
-vprox vops ingest        # one-shot archive ingest
-vprox vops accounts      # list IP accounts as JSON
-vprox vops threats       # list flagged IPs (score ≥ 50)
-vprox vops cache         # manage intel cache
+vops start                # foreground server (default: :8889)
+vops start -d             # start as background service
+vops stop                 # stop vOps service
+vops restart              # restart vOps service
+vops status               # show status and database stats
+vops ingest                # one-shot archive ingest
+vops -a                   # list IP accounts as JSON
+vops -t                   # list flagged IPs (score ≥ 50)
+vops vprox start          # start the embedded vProx proxy
 ```
 
 For full setup including authentication, API key configuration, and block/unblock, see the [Installing vOps](./INSTALLATION.md#installing-vops) section in `INSTALLATION.md`.
@@ -118,17 +118,16 @@ For full setup including authentication, API key configuration, and block/unbloc
 ### Run
 
 ```bash
-vProx start             # foreground, listens on :3000 by default
-vProx start -d          # start as systemd service (daemon)
-vProx start --with-vops # start proxy + vOps in integrated mode
-vProx stop              # stop the service
-vProx restart           # restart the service
-vProx --validate        # validate config and exit
-vProx completion bash   # generate bash shell completion script
-vProx completion zsh    # generate zsh shell completion script
-vProx completion fish   # generate fish shell completion script
+vops vprox start         # foreground, listens on :3000 by default
+vops vprox start -d      # start as systemd service (daemon)
+vops vprox stop          # stop the service
+vops vprox restart       # restart the service
+vops vprox status        # show service state and basic stats
+vops vprox view          # tail vProx service logs
 ```
 
+The proxy is also buildable as its own binary (`make build-vprox`, `go run ./cmd/vprox`) for local development and diagnostics — see the [advanced standalone reference](./CLI_FLAGS_GUIDE.md#advanced-standalone-vprox-binary-devdiagnostics-only) in `CLI_FLAGS_GUIDE.md` for its full flag set (`--validate`, `--with-vops`, `completion`, etc.).
+
 ### Architecture
 
 vProx follows a modular internal architecture with clearly separated concerns:
@@ -173,7 +172,7 @@ Override the config base path:
 ```bash
 export VOPS_HOME=/opt/vops
 # or
-vProx --home /opt/vops
+vops --home /opt/vops
 ```
 
 For the complete CLI flag reference, see [`CLI_FLAGS_GUIDE.md`](./CLI_FLAGS_GUIDE.md).
diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md
index a12c1ef..96f5264 100644
--- a/docs/UPGRADE.md
+++ b/docs/UPGRADE.md
@@ -86,7 +86,7 @@ $HOME/.vProx/
 ### 0. **Access counter persistence + backup reset flag**
 - **New state file**: `$HOME/.vProx/data/access-counts.json`
 - **Behavior**: source access counters now persist across restart and backup by default
-- **Manual reset**: `vProx backup --reset_count` (alias: `--reset-count`)
+- **Manual reset**: `./.build/vProx --new-backup --reset_count` (alias: `--reset-count`)
 - **Benefit**: stable long-term `src_count` values unless explicitly reset
 
 ### 1. **Geolocation Database**