Sync CLI docs and refresh compiled workflow artifacts for consistency checker (#2115)

* Initial plan

* docs: sync CLI flag documentation with implementation

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/3d1c4bc9-2d27-4992-8793-cdafb4ec1fb4

* docs: clarify DIFC proxy flag wording

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/3d1c4bc9-2d27-4992-8793-cdafb4ec1fb4

* Update docs/usage.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Initial plan

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* chore: rebase main and recompile workflows

Agent-Logs-Url: https://github.com/github/gh-aw-firewall/sessions/4f16749e-8ad3-433a-a9a6-e3eff88697da

Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

* Revert broken lock file changes

The Copilot agent incorrectly replaced all github/gh-aw-actions/setup@SHA
references with ./actions/setup (a local path that doesn't exist) across
all lock files. This reverts those changes, keeping only the documentation
updates to docs/usage.md and docs-site CLI reference.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Landon Cox <landon.cox@microsoft.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: 4 people

docs-site/src/content/docs/reference/cli-reference.md

@@ -19,6 +19,7 @@ awf [options] -- <command>
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
+| `--config <path>` | string | — | Path to AWF JSON/YAML config file (use `-` to read from stdin) |
 | `--allow-domains <domains>` | string | — | Comma-separated list of allowed domains (optional; if not specified, all network access is blocked) |
 | `--allow-domains-file <path>` | string | — | Path to file containing allowed domains |
 | `--ruleset-file <path>` | string | `[]` | YAML rule file for domain allowlisting (repeatable) |
@@ -35,6 +36,7 @@ awf [options] -- <command>
 | `--image-registry <url>` | string | `ghcr.io/github/gh-aw-firewall` | Container image registry |
 | `--image-tag <tag>` | string | `latest` | Container image tag. Supports optional per-image digest pinning: `<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...` |
 | `--skip-pull` | flag | `false` | Use local images without pulling from registry |
+| `--docker-host <socket>` | string | auto-detected | Docker socket for AWF's own containers |
 | `-e, --env <KEY=VALUE>` | string | `[]` | Environment variable (repeatable) |
 | `--env-all` | flag | `false` | Pass all host environment variables |
 | `--exclude-env <name>` | string | `[]` | Exclude a variable from `--env-all` passthrough (repeatable) |
@@ -44,8 +46,10 @@ awf [options] -- <command>
 | `--memory-limit <limit>` | string | `6g` | Memory limit for the agent container |
 | `--dns-servers <servers>` | string | Auto-detected | Trusted DNS servers (comma-separated; auto-detected from host, falls back to `8.8.8.8,8.8.4.4`) |
 | `--dns-over-https [resolver-url]` | optional string | `https://dns.google/dns-query` | Enable DNS-over-HTTPS via sidecar proxy |
+| `--upstream-proxy <url>` | string | auto-detected | Upstream (corporate) proxy URL for Squid to chain through |
 | `--proxy-logs-dir <path>` | string | — | Directory to save Squid proxy logs to |
 | `--audit-dir <path>` | string | — | Directory for firewall audit artifacts |
+| `--session-state-dir <path>` | string | — | Directory to save Copilot CLI session state |
 | `--enable-host-access` | flag | `false` | Enable access to host services via host.docker.internal |
 | `--allow-host-ports <ports>` | string | `80,443` | Ports to allow when using --enable-host-access |
 | `--allow-host-service-ports <ports>` | string | — | Ports to allow ONLY to host gateway (for GitHub Actions `services:`) |
@@ -58,15 +62,34 @@ awf [options] -- <command>
 | `--openai-api-base-path <path>` | string | — | Base path prefix for OpenAI API requests |
 | `--anthropic-api-target <host>` | string | `api.anthropic.com` | Target hostname for Anthropic API requests |
 | `--anthropic-api-base-path <path>` | string | — | Base path prefix for Anthropic API requests |
+| `--gemini-api-target <host>` | string | `generativelanguage.googleapis.com` | Target hostname for Gemini API requests |
+| `--gemini-api-base-path <path>` | string | — | Base path prefix for Gemini API requests |
 | `--rate-limit-rpm <n>` | number | `600` | Max requests per minute per provider |
 | `--rate-limit-rph <n>` | number | `10000` | Max requests per hour per provider |
 | `--rate-limit-bytes-pm <n>` | number | `52428800` (~50 MB) | Max request bytes per minute per provider |
 | `--no-rate-limit` | flag | — | Disable rate limiting in API proxy |
+| `--difc-proxy-host <host:port>` | string | — | Connect to external DIFC proxy and enable CLI proxy sidecar |
+| `--difc-proxy-ca-cert <path>` | string | — | Path to TLS CA cert for external DIFC proxy verification |
+| `--diagnostic-logs` | flag | `false` | Collect diagnostics on non-zero exit |
 | `-V, --version` | flag | — | Display version |
 | `-h, --help` | flag | — | Display help |
 
 ## Options Details
 
+### `--config <path>`
+
+Load AWF options from a JSON or YAML config file. Use `-` to read config from stdin.
+
+CLI flags always take precedence over values loaded from the config file.
+
+```bash
+# Load from file
+sudo awf --config ./awf.yml -- curl https://api.github.com
+
+# Load from stdin
+cat awf.yml | sudo awf --config - -- curl https://api.github.com
+```
+
 ### `--allow-domains <domains>`
 
 Comma-separated list of allowed domains. Domains automatically match all subdomains. Supports wildcard patterns, protocol-specific filtering, and special keywords.
@@ -370,6 +393,18 @@ When using `--skip-pull`, you are responsible for verifying image authenticity.
 The `--skip-pull` flag cannot be used with `--build-local` since building images requires pulling base images from the registry.
 :::
 
+### `--docker-host <socket>`
+
+Override the Docker socket used by AWF for its own container operations.
+
+```bash
+sudo awf --docker-host unix:///run/user/1000/docker.sock \
+  --allow-domains github.com \
+  -- curl https://api.github.com
+```
+
+The value must be a `unix://` socket URI.
+
 ### `-e, --env <KEY=VALUE>`
 
 Pass environment variable to container. Can be specified multiple times.
@@ -508,6 +543,18 @@ Enable DNS-over-HTTPS (DoH) via a sidecar proxy. When enabled, DNS queries are e
 Use `--dns-over-https` without a value to use the Google DNS default. Provide a custom URL only if your environment requires a specific resolver.
 :::
 
+### `--upstream-proxy <url>`
+
+Configure Squid to chain outbound traffic through an upstream corporate proxy.
+
+```bash
+sudo awf --upstream-proxy http://proxy.corp.com:3128 \
+  --allow-domains github.com \
+  -- curl https://api.github.com
+```
+
+If omitted, AWF auto-detects host `https_proxy`/`http_proxy` settings.
+
 ### `--enable-host-access`
 
 Enable access to host services via `host.docker.internal`. This allows containers to connect to services running on the host machine (e.g., local development servers, MCP gateways).
@@ -605,6 +652,16 @@ ls ./audit/
 Use `--audit-dir` in CI/CD pipelines to capture firewall configuration for audit trails. Can also be set via the `AWF_AUDIT_DIR` environment variable.
 :::
 
+### `--session-state-dir <path>`
+
+Directory to persist Copilot CLI session state (such as `events.jsonl`) during execution.
+
+```bash
+sudo awf --session-state-dir ./session-state \
+  --allow-domains github.com \
+  -- copilot --prompt "hello"
+```
+
 ### `--agent-image <value>`
 
 Specify the agent container image to use. Supports pre-built presets or custom base images.
@@ -777,6 +834,35 @@ sudo -E awf --enable-api-proxy \
   -- command
 ```
 
+### `--gemini-api-target <host>`
+
+Target hostname for Gemini API requests. Useful for private gateways or compatible Gemini endpoints.
+
+- **Default:** `generativelanguage.googleapis.com`
+- **Requires:** `--enable-api-proxy`
+
+```bash
+sudo -E awf --enable-api-proxy \
+  --gemini-api-target ai-gateway.internal.example.com \
+  --allow-domains ai-gateway.internal.example.com \
+  -- command
+```
+
+### `--gemini-api-base-path <path>`
+
+Base path prefix prepended to Gemini API requests.
+
+- **Default:** none
+- **Requires:** `--enable-api-proxy`
+
+```bash
+sudo -E awf --enable-api-proxy \
+  --gemini-api-target ai-gateway.internal.example.com \
+  --gemini-api-base-path /gemini \
+  --allow-domains ai-gateway.internal.example.com \
+  -- command
+```
+
 ### `--rate-limit-rpm <n>`
 
 Maximum number of requests per minute per provider. Rate limiting is opt-in — it is only enabled when at least one `--rate-limit-*` flag is provided.
@@ -831,6 +917,33 @@ sudo -E awf --enable-api-proxy --no-rate-limit \
   -- command
 ```
 
+### `--difc-proxy-host <host:port>`
+
+Connect to an external DIFC proxy (`mcpg`) and enable the CLI proxy sidecar for `gh` command routing.
+
+```bash
+sudo awf --difc-proxy-host 127.0.0.1:5555 \
+  --allow-domains github.com \
+  -- gh repo view github/gh-aw-firewall
+```
+
+### `--difc-proxy-ca-cert <path>`
+
+Path to a CA certificate written by the external DIFC proxy. Recommended when using `--difc-proxy-host` over TLS.
+
+```bash
+sudo awf --difc-proxy-host 127.0.0.1:5555 \
+  --difc-proxy-ca-cert /tmp/mcpg-ca.crt \
+  --allow-domains github.com \
+  -- gh repo view github/gh-aw-firewall
+```
+
+### `--diagnostic-logs`
+
+Collect container logs, exit state, and a sanitized config snapshot when the wrapped command exits non-zero.
+
+Diagnostic artifacts are written to `<workDir>/diagnostics/` (or `<audit-dir>/diagnostics/` when `--audit-dir` is set).
+
 :::caution
 When using a custom `--openai-api-target` or `--anthropic-api-target`, you must add the target domain to `--allow-domains` so the firewall permits outbound traffic. AWF emits a warning if a custom target is set but not in the allowlist.
 :::
@@ -963,6 +1076,7 @@ awf predownload [options]
 | `--image-tag <tag>` | string | `latest` | Container image tag (applies to squid, agent, agent-act, api-proxy, and cli-proxy images). Supports optional digest metadata — see [`--image-tag`](#--image-tag-tag) for format details. |
 | `--agent-image <value>` | string | `default` | Agent image preset (`default`, `act`) or custom image |
 | `--enable-api-proxy` | flag | `false` | Also download the API proxy image |
+| `--difc-proxy` | flag | `false` | Also download the CLI proxy image used when runtime flag `--difc-proxy-host` is set |
 
 :::tip
 After pre-downloading, use `--skip-pull` on subsequent runs to skip pulling images at runtime.
@@ -977,6 +1091,9 @@ awf predownload
 # Pre-download including the API proxy image
 awf predownload --enable-api-proxy
 
+# Pre-download including the CLI proxy image
+awf predownload --difc-proxy
+
 # Pre-download a specific version
 awf predownload --image-tag v0.3.0
 

docs/usage.md

@@ -6,6 +6,7 @@
 sudo awf [options] -- <command>
 
 Options:
+  --config <path>              Path to AWF JSON/YAML config file (use "-" to read from stdin)
   -d, --allow-domains <domains>  Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                              - github.com: exact domain + subdomains (HTTP & HTTPS)
                              - *.github.com: any subdomain of github.com
@@ -43,31 +44,44 @@ Options:
                                    default → agent:<tag>
                                    act     → agent-act:<tag>
   --skip-pull                  Use local images without pulling from registry (requires images to be
-                               pre-downloaded) (default: false)
+                                pre-downloaded) (default: false)
+  --docker-host <socket>       Docker socket for AWF's own containers (default: auto-detect from
+                               DOCKER_HOST env). Example: unix:///run/user/1000/docker.sock
   -e, --env <KEY=VALUE>        Additional environment variables to pass to container (can be
-                               specified multiple times)
+                                specified multiple times)
   --env-all                    Pass all host environment variables to container (excludes system vars
-                               like PATH) (default: false)
-  -v, --mount <path:path>      Volume mount (can be specified multiple times). Format:
-                               host_path:container_path[:ro|rw]
+                                like PATH) (default: false)
+  --exclude-env <name>         Exclude a specific environment variable from --env-all passthrough
+                               (can be specified multiple times)
+  --env-file <path>            Read environment variables from a file (KEY=VALUE format, one per line)
+  -v, --mount <host_path:container_path[:ro|rw]>  Volume mount (can be specified multiple times). Format:
+                                host_path:container_path[:ro|rw]
   --container-workdir <dir>    Working directory inside the container (should match GITHUB_WORKSPACE
                                for path consistency)
   --dns-servers <servers>      Comma-separated list of trusted DNS servers. DNS traffic is ONLY
-                               allowed to these servers (default: 8.8.8.8,8.8.4.4)
+                               allowed to these servers (default: auto-detected from host resolvers,
+                               falls back to 8.8.8.8,8.8.4.4)
+  --upstream-proxy <url>       Upstream (corporate) proxy URL for Squid to chain through.
+                               Auto-detected from host https_proxy/http_proxy if not set.
   --proxy-logs-dir <path>      Directory to save Squid proxy logs to (writes access.log directly to
-                               this directory)
+                                this directory)
+  --audit-dir <path>           Directory for firewall audit artifacts (configs, policy manifest,
+                               iptables state)
   --session-state-dir <path>   Directory to save Copilot CLI session state (events.jsonl, session
-                               data). Writes directly during execution (timeout-safe, predictable
-                               path). Also configurable via AWF_SESSION_STATE_DIR env var.
+                                data). Writes directly during execution (timeout-safe, predictable
+                                path). Also configurable via AWF_SESSION_STATE_DIR env var.
   --enable-host-access         Enable access to host services via host.docker.internal. Security
                                warning: When combined with --allow-domains host.docker.internal,
                                containers can access ANY service on the host machine. (default: false)
   --allow-host-ports <ports>   Comma-separated list of ports or port ranges to allow when using
-                               --enable-host-access. By default, only ports 80 and 443 are allowed.
-                               Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or
-                               --allow-host-ports 3000-3010,8000-8090
+                                --enable-host-access. By default, only ports 80 and 443 are allowed.
+                                Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or
+                                --allow-host-ports 3000-3010,8000-8090
+  --allow-host-service-ports <ports> Comma-separated ports to allow ONLY to host gateway
+                               (for GitHub Actions services). Auto-enables host access.
+                               Example: --allow-host-service-ports 5432,6379
   --ssl-bump                   Enable SSL Bump for HTTPS content inspection (allows URL path
-                               filtering for HTTPS) (default: false)
+                                filtering for HTTPS) (default: false)
   --allow-urls <urls>          Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
                                Supports wildcards: https://github.com/myorg/*
   --enable-api-proxy           Enable API proxy sidecar for holding authentication credentials.
@@ -76,29 +90,46 @@ Options:
   --copilot-api-target <host>  Target hostname for Copilot API requests
                                (default: api.githubcopilot.com)
   --openai-api-target <host>   Target hostname for OpenAI API requests (default: api.openai.com)
+  --openai-api-base-path <path> Base path prefix for OpenAI API requests
   --anthropic-api-target <host> Target hostname for Anthropic API requests
-                               (default: api.anthropic.com)
+                                (default: api.anthropic.com)
+  --anthropic-api-base-path <path> Base path prefix for Anthropic API requests
+  --gemini-api-target <host>   Target hostname for Gemini API requests
+                               (default: generativelanguage.googleapis.com)
+  --gemini-api-base-path <path> Base path prefix for Gemini API requests
   --rate-limit-rpm <n>         Max requests per minute per provider (requires --enable-api-proxy)
   --rate-limit-rph <n>         Max requests per hour per provider (requires --enable-api-proxy)
   --rate-limit-bytes-pm <n>    Max request bytes per minute per provider (requires --enable-api-proxy)
   --no-rate-limit              Disable rate limiting in the API proxy (requires --enable-api-proxy)
+  --difc-proxy-host <host:port> Connect to an external DIFC proxy (Multi-Cloud Proxy Gateway, "mcpg")
+                               and enable the CLI proxy sidecar for gh command routing
+  --difc-proxy-ca-cert <path>  Path to TLS CA cert written by external DIFC proxy
   --ruleset-file <path>        YAML rule file for domain allowlisting (repeatable).
-                               Schema: version: 1, rules: [{domain, subdomains}]
+                                Schema: version: 1, rules: [{domain, subdomains}]
   --dns-over-https [url]       Enable DNS-over-HTTPS via sidecar proxy
                                (default: https://dns.google/dns-query)
-  --memory-limit <limit>       Memory limit for the agent container (default: 2g)
-                               Examples: 1g, 4g, 512m
+  --memory-limit <limit>       Memory limit for the agent container (default: 6g)
+                                Examples: 1g, 4g, 512m
   --enable-dind                Enable Docker-in-Docker by exposing host Docker socket.
                                WARNING: allows firewall bypass via docker run (default: false)
   --enable-dlp                 Enable DLP (Data Loss Prevention) scanning to block credential
-                               exfiltration in outbound request URLs. (default: false)
+                                exfiltration in outbound request URLs. (default: false)
+  --diagnostic-logs            Collect container logs, exit state, and sanitized config on non-zero
+                               exit. Written to <workDir>/diagnostics/ (or <audit-dir>/diagnostics/)
   -V, --version                Output the version number
   -h, --help                   Display help for command
 
 Arguments:
   command                      Command to execute (wrap in quotes, use -- separator)
 
 Commands:
+  predownload [options]        Pre-download Docker images for offline use or faster startup
+    --image-registry <registry> Container image registry (default: ghcr.io/github/gh-aw-firewall)
+    --image-tag <tag>          Container image tag (default: latest)
+    --agent-image <value>      Agent image preset (default, act) or custom image
+    --enable-api-proxy         Also download the API proxy image
+    --difc-proxy               Also download the CLI proxy image (for --difc-proxy-host)
+
   logs [options]               View and analyze Squid proxy logs
     -f, --follow               Follow log output in real-time (like tail -f)
     --format <format>          Output format: raw, pretty (colorized), json
@@ -113,6 +144,13 @@ Commands:
   logs summary [options]       Generate summary report (markdown by default)
     --format <format>          Output format: json, markdown, pretty
     --source <path>            Path to log directory or "running" for live container
+
+  logs audit [options]         Show firewall audit with policy rule matching
+    --format <format>          Output format: json, markdown, pretty
+    --source <path>            Path to log directory or "running" for live container
+    --rule <id>                Filter to specific rule ID
+    --domain <domain>          Filter to specific domain
+    --decision <decision>      Filter to "allowed" or "denied"
 ```
 
 ## Basic Examples