docs: add documentation for awf logs stats and summary commands

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

Author: Copilot

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

@@ -232,6 +232,118 @@ awf logs --source running -f
 Log sources are auto-discovered in this order: running containers, `AWF_LOGS_DIR` environment variable, then preserved log directories in `/tmp/squid-logs-*`.
 :::
 
+### `awf logs stats`
+
+Show aggregated statistics from firewall logs.
+
+```bash
+awf logs stats [options]
+```
+
+:::note[stats vs summary]
+Use `awf logs stats` for terminal output (defaults to colorized `pretty` format). Use `awf logs summary` for CI/CD integration (defaults to `markdown` format for `$GITHUB_STEP_SUMMARY`). Both commands provide the same data in different default formats.
+:::
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--format <format>` | string | `pretty` | Output format: `json`, `markdown`, `pretty` |
+| `--source <path>` | string | auto | Path to log directory or `running` for live container |
+
+#### Output Formats
+
+| Format | Description |
+|--------|-------------|
+| `pretty` | Colorized terminal output with summary and domain breakdown (default) |
+| `markdown` | Markdown table format suitable for documentation |
+| `json` | Structured JSON for programmatic consumption |
+
+#### Examples
+
+```bash
+# Show stats with colorized terminal output
+awf logs stats
+
+# Get stats in JSON format for scripting
+awf logs stats --format json
+
+# Get stats in markdown format
+awf logs stats --format markdown
+
+# Use a specific log directory
+awf logs stats --source /tmp/squid-logs-1234567890
+```
+
+#### Example Output (Pretty)
+
+```
+Firewall Statistics
+────────────────────────────────────────
+
+Total Requests:  150
+Allowed:         145 (96.7%)
+Denied:          5 (3.3%)
+Unique Domains:  12
+
+Domains:
+  api.github.com       50 allowed, 0 denied
+  registry.npmjs.org   95 allowed, 0 denied
+  evil.com             0 allowed, 5 denied
+```
+
+### `awf logs summary`
+
+Generate summary report optimized for GitHub Actions step summaries.
+
+```bash
+awf logs summary [options]
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `--format <format>` | string | `markdown` | Output format: `json`, `markdown`, `pretty` |
+| `--source <path>` | string | auto | Path to log directory or `running` for live container |
+
+:::tip[GitHub Actions]
+The `summary` command defaults to markdown format, making it perfect for piping directly to `$GITHUB_STEP_SUMMARY`.
+:::
+
+#### Examples
+
+```bash
+# Generate markdown summary (default)
+awf logs summary
+
+# Add to GitHub Actions step summary
+awf logs summary >> $GITHUB_STEP_SUMMARY
+
+# Get summary in JSON format
+awf logs summary --format json
+
+# Get summary with colorized terminal output
+awf logs summary --format pretty
+```
+
+#### Example Output (Markdown)
+
+```markdown
+### Firewall Activity
+
+<details>
+<summary>150 requests | 145 allowed | 5 blocked | 12 unique domains</summary>
+
+| Domain | Allowed | Denied |
+|--------|---------|--------|
+| api.github.com | 50 | 0 |
+| registry.npmjs.org | 95 | 0 |
+| evil.com | 0 | 5 |
+
+</details>
+```
+
 ## See Also
 
 - [Quick Start Guide](/gh-aw-firewall/quickstart) - Getting started with examples

docs/github_actions.md

@@ -87,6 +87,79 @@ If you currently have manual Squid proxy configuration, you can replace it with
       'copilot --prompt "..."'
 ```
 
+## Generating Firewall Summaries
+
+The `awf logs summary` command generates markdown output optimized for GitHub Actions step summaries, eliminating the need for manual log parsing scripts.
+
+### Basic Usage
+
+```yaml
+- name: Run command through firewall
+  run: |
+    sudo awf \
+      --allow-domains github.com,api.github.com \
+      'your-command-here'
+
+- name: Generate firewall summary
+  if: always()
+  run: awf logs summary >> $GITHUB_STEP_SUMMARY
+```
+
+### Complete Example
+
+```yaml
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Firewall
+        run: |
+          curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash
+
+      - name: Test with Firewall
+        env:
+          GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }}
+        run: |
+          sudo -E awf \
+            --allow-domains github.com,api.github.com,registry.npmjs.org \
+            'npx @github/copilot@latest --prompt "Hello"'
+
+      - name: Generate firewall summary
+        if: always()
+        run: awf logs summary >> $GITHUB_STEP_SUMMARY
+```
+
+The summary appears as a collapsible section in your workflow run showing:
+- Total requests, allowed, and blocked counts
+- Table of all domains with their allowed/denied request counts
+
+### Output Formats
+
+```bash
+# Default: Markdown (for $GITHUB_STEP_SUMMARY)
+awf logs summary
+
+# JSON format for programmatic processing
+awf logs summary --format json
+
+# Pretty format for terminal output
+awf logs summary --format pretty
+```
+
+### Getting Statistics
+
+For detailed statistics without adding to step summary:
+
+```bash
+# Pretty terminal output
+awf logs stats
+
+# JSON for scripting
+awf logs stats --format json
+```
+
 ## MCP Server Configuration for Copilot CLI
 
 ### Overview

docs/logging_quickref.md

@@ -188,24 +188,50 @@ docker exec awf-squid grep "curl" /var/log/squid/access.log
 
 ## Statistics
 
-### Total Requests
+### Using `awf logs stats`
+
+Get aggregated statistics including total requests, allowed/denied counts, and per-domain breakdown:
+
+```bash
+# Pretty terminal output (default)
+awf logs stats
+
+# JSON format for scripting
+awf logs stats --format json
+
+# Markdown format
+awf logs stats --format markdown
+```
+
+### Using `awf logs summary` for GitHub Actions
+
+Generate a markdown summary optimized for GitHub Actions step summaries:
+
+```bash
+# Add summary to GitHub Actions step summary
+awf logs summary >> $GITHUB_STEP_SUMMARY
+```
+
+### Manual Statistics Queries
+
+#### Total Requests
 ```bash
 docker exec awf-squid wc -l /var/log/squid/access.log
 ```
 
-### Blocked vs Allowed Count
+#### Blocked vs Allowed Count
 ```bash
 echo "Blocked: $(docker exec awf-squid grep -c TCP_DENIED /var/log/squid/access.log)"
 echo "Allowed: $(docker exec awf-squid grep -cE 'TCP_TUNNEL|TCP_MISS' /var/log/squid/access.log)"
 ```
 
-### Top 10 Accessed Domains
+#### Top 10 Accessed Domains
 ```bash
 docker exec awf-squid awk '{print $3}' /var/log/squid/access.log | \
   sort | uniq -c | sort -rn | head -10
 ```
 
-### Unique Client IPs
+#### Unique Client IPs
 ```bash
 docker exec awf-squid awk '{split($2,a,":"); print a[1]}' /var/log/squid/access.log | sort -u
 ```

docs/usage.md

@@ -538,6 +538,52 @@ awf logs --format json | jq -s 'group_by(.isAllowed) | map({allowed: .[0].isAllo
 
 ## Log Analysis
 
+### Using `awf logs stats`
+
+Get aggregated statistics from firewall logs including total requests, allowed/denied counts, and per-domain breakdown:
+
+```bash
+# Pretty terminal output (default)
+awf logs stats
+
+# JSON format for scripting
+awf logs stats --format json
+
+# Markdown format
+awf logs stats --format markdown
+```
+
+Example output:
+```
+Firewall Statistics
+────────────────────────────────────────
+
+Total Requests:  150
+Allowed:         145 (96.7%)
+Denied:          5 (3.3%)
+Unique Domains:  12
+
+Domains:
+  api.github.com       50 allowed, 0 denied
+  registry.npmjs.org   95 allowed, 0 denied
+  evil.com             0 allowed, 5 denied
+```
+
+### Using `awf logs summary` (GitHub Actions)
+
+Generate a markdown summary optimized for GitHub Actions:
+
+```bash
+# Generate markdown summary and append to step summary
+awf logs summary >> $GITHUB_STEP_SUMMARY
+```
+
+This creates a collapsible summary in your GitHub Actions workflow output showing all allowed and blocked domains.
+
+### Manual Log Queries
+
+For more granular analysis, you can query the logs directly:
+
 Find all blocked domains:
 ```bash
 docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u