docs: document flag validation constraints

[Mossaka]

Summary

• Adds "Flag Combinations and Constraints" section to docs/usage.md
• Documents --skip-pull + --build-local incompatibility with exact error message
• Documents --allow-host-ports requiring --enable-host-access with exact error message
• Includes correct vs incorrect usage examples for each constraint

Fixes #496

Test plan

• Verify docs render correctly
• Verify error messages match actual CLI output

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds documentation for CLI flag validation constraints in docs/usage.md to help users understand incompatible flag combinations and required dependencies (Fixes #496).

Changes:

• Adds a new “Flag Combinations and Constraints” section.
• Documents --skip-pull + --build-local incompatibility with examples.
• Documents --allow-host-ports requiring --enable-host-access with examples.

Comments suppressed due to low confidence (1)

docs/usage.md:674

• Same as above: the documented error output uses Error: but the CLI emits this via logger.error('❌ --allow-host-ports requires --enable-host-access to be set'), which results in a [ERROR]-prefixed line and includes the ❌. Please adjust the shown output so it matches the actual CLI output format/message.

# ❌ Error: missing dependency flag
sudo awf --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
# Error: --allow-host-ports requires --enable-host-access to be set

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documented CLI output here doesn’t match what the CLI actually prints. awf logs validation failures via logger.error(...), which prefixes output with [ERROR] and (for these cases) includes a leading ❌, not Error:. Please update the example output lines so they match the real CLI output format/message (including the ❌ prefix, and consider whether to include the [ERROR] prefix as well).

This issue also appears on line 671 of the same file.

[Copilot]

The “correct” example for --allow-host-ports uses --allow-domains github.com, but --allow-host-ports only affects access to host services (e.g., host.docker.internal / localhost). This example is valid syntactically, but it doesn’t demonstrate a working/meaningful host-access scenario; consider updating it to include --allow-domains host.docker.internal (or localhost) to align with the explanation and earlier examples in this doc.

Suggested change

	sudo awf --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
	# Error: --allow-host-ports requires --enable-host-access to be set
	# ✅ Correct: include --enable-host-access
	sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains github.com -- your-command
	sudo awf --allow-host-ports 3000,8080 --allow-domains host.docker.internal -- your-command
	# Error: --allow-host-ports requires --enable-host-access to be set
	# ✅ Correct: include --enable-host-access
	sudo awf --enable-host-access --allow-host-ports 3000,8080 --allow-domains host.docker.internal -- your-command

[github-actions]

Smoke Test Results

• ✅ GitHub MCP: test: add --allow-host-ports validation tests #1221 test: add --allow-host-ports validation tests, test: add --proxy-logs-dir edge case coverage #1220 test: add --proxy-logs-dir edge case coverage
• ✅ Playwright: GitHub page title contains "GitHub"
• ✅ File write: /tmp/gh-aw/agent/smoke-test-claude-22964980615.txt created
• ✅ Bash verify: File contents confirmed

Overall: PASS

💥 [THE END] — Illustrated by Smoke Claude for issue #1230

[github-actions]

Smoke Test Results — @Mossaka

Test	Result
GitHub MCP: Last 2 merged PRs	✅ #1221 test: add --allow-host-ports validation tests, #1220 test: add --proxy-logs-dir edge case coverage
Playwright: github.com title contains "GitHub"	✅
File write: smoke-test-copilot-22964980573.txt	✅
Bash: file read back via cat	✅

Overall: PASS

📰 BREAKING: Report filed by Smoke Copilot for issue #1230

[github-actions]

🏗️ Build Test Suite Results

❌ ALL ECOSYSTEMS FAILED TO CLONE — gh CLI is not authenticated in this environment (GH_TOKEN not set).

Ecosystem	Project	Build/Install	Tests	Status
Bun	elysia	❌	N/A	❌ CLONE_FAILED
Bun	hono	❌	N/A	❌ CLONE_FAILED
C++	fmt	❌	N/A	❌ CLONE_FAILED
C++	json	❌	N/A	❌ CLONE_FAILED
Deno	oak	❌	N/A	❌ CLONE_FAILED
Deno	std	❌	N/A	❌ CLONE_FAILED
.NET	hello-world	❌	N/A	❌ CLONE_FAILED
.NET	json-parse	❌	N/A	❌ CLONE_FAILED
Go	color	❌	N/A	❌ CLONE_FAILED
Go	env	❌	N/A	❌ CLONE_FAILED
Go	uuid	❌	N/A	❌ CLONE_FAILED
Java	gson	❌	N/A	❌ CLONE_FAILED
Java	caffeine	❌	N/A	❌ CLONE_FAILED
Node.js	clsx	❌	N/A	❌ CLONE_FAILED
Node.js	execa	❌	N/A	❌ CLONE_FAILED
Node.js	p-limit	❌	N/A	❌ CLONE_FAILED
Rust	fd	❌	N/A	❌ CLONE_FAILED
Rust	zoxide	❌	N/A	❌ CLONE_FAILED

Overall: 0/8 ecosystems passed — ❌ FAIL

Error Details

All 8 repository clone attempts failed with:

gh: To use GitHub CLI in a GitHub Actions workflow, set the GH_TOKEN environment variable. Example:
  env:
    GH_TOKEN: ${{ github.token }}

The gh CLI is not authenticated. The workflow needs GH_TOKEN to be set in the environment in order to clone the test repositories.

Generated by Build Test Suite for issue #1230 · ◷

[github-actions]

Smoke test results (run 22964980596):
Merged PRs reviewed: test: add --allow-host-ports validation tests; test: add --proxy-logs-dir edge case coverage
GitHub MCP review: OK
safeinputs-gh pr list: OK
Playwright title check: OK
Tavily search: FAIL (tool unavailable)
File write + cat: OK
Discussion comment: OK
Build npm ci && npm run build: OK
Overall: FAIL

🔮 The oracle has spoken through Smoke Codex for issue #1230

[github-actions]

Smoke Test Results

• ✅ GitHub MCP: test(docker): verify capsh execution chain after PR #715 #1240 test(docker): verify capsh execution chain after PR fix: eliminate nested bash layer in chroot command execution for Java/.NET #715 | test: expand credential hiding tests to all 14 protected paths #1163 test: expand credential hiding tests to all 14 protected paths
• ✅ Playwright: GitHub page title verified ("GitHub · Change is constant...")
• ✅ File Write: /tmp/gh-aw/agent/smoke-test-claude-22969580974.txt created
• ✅ Bash: File contents verified

Overall: PASS

💥 [THE END] — Illustrated by Smoke Claude for issue #1230

[github-actions]

Smoke Test Results

✅ GitHub MCP — Last 2 merged PRs:

• test(docker): verify capsh execution chain after PR #715 #1240 test(docker): verify capsh execution chain after PR #715
• fix(cli): clear LD_PRELOAD after one-shot-token library loads #1232 fix(cli): clear LD_PRELOAD after one-shot-token library loads

✅ Playwright — github.com title contains "GitHub"
✅ File Writing — /tmp/gh-aw/agent/smoke-test-copilot-22969580964.txt created
✅ Bash Tool — File verified via cat

Overall: PASS | Author: @Mossaka

📰 BREAKING: Report filed by Smoke Copilot for issue #1230

[github-actions]

PR titles: feat(cli): add predownload command to pre-pull container images
PR titles: fix(cli): fix secure_getenv() bypass of one-shot token protection
GitHub MCP (last 2 merged PRs): ✅
Safeinputs GH PR list: ✅
Playwright title check: ✅
Tavily web search: ❌
File write: ✅
Bash cat verify: ✅
Discussion query/comment: ✅
Build (npm ci && npm run build): ✅
Overall: FAIL

🔮 The oracle has spoken through Smoke Codex for issue #1230