docs: clarify --image-tag behavior with agent-image presets

[Mossaka]

Summary

• Updated --image-tag help text in CLI to explain that the image name varies by --agent-image preset (default → agent:<tag>, act → agent-act:<tag>)
• Updated docs/usage.md with the same clarification

Fixes #502

Test plan

• npm run build passes
• npm test passes (839 tests)
• npm run lint passes (warnings only, no errors)
• Verify awf --help shows updated --image-tag description

🤖 Generated with Claude Code

[github-actions]

✅ Coverage Check Passed

Overall Coverage

Metric	Base	PR	Delta
Lines	82.37%	82.51%	📈 +0.14%
Statements	82.36%	82.50%	📈 +0.14%
Functions	82.60%	82.60%	➡️ +0.00%
Branches	74.47%	74.56%	📈 +0.09%

📁 Per-file Coverage Changes (1 files)

File	Lines (Before → After)	Statements (Before → After)
src/docker-manager.ts	83.4% → 84.0% (+0.54%)	82.8% → 83.3% (+0.52%)

---

Coverage comparison generated by scripts/ci/compare-coverage.ts

[Copilot]

Pull request overview

Updates CLI help and user docs to clarify how --image-tag maps to different agent image names depending on the --agent-image preset (per issue #502).

Changes:

• Expanded --image-tag help text in the CLI to document preset-dependent agent image naming (agent:<tag> vs agent-act:<tag>).
• Updated docs/usage.md to include the same clarification alongside the --image-tag option.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
src/cli.ts	Extends --image-tag help text with preset-dependent image-name mapping.
docs/usage.md	Mirrors the CLI clarification in the usage documentation.

---

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

[Copilot]

The new help text implies --image-tag always applies to both Squid and agent images, but when --build-local is set both services are built locally (no image: is set in the generated compose), so the tag is effectively ignored. Consider qualifying this description with something like “when pulling pre-built images from --image-registry (i.e., without --build-local)” and/or noting that --image-tag doesn’t affect locally-built images.

Suggested change

	'Container image tag (applies to both squid and agent images)\n' +
	'Container image tag for pre-built images from --image-registry (applies to both squid and agent images when not using --build-local; has no effect on locally-built images)\n' +

[Copilot]

This clarification is accurate for preset GHCR images, but --image-tag is ignored when --build-local is used (compose builds services locally and doesn’t use registry/tag). Consider adding a short qualifier (e.g., “when pulling preset images / without --build-local”) to avoid implying the name/tag mapping always applies.

Suggested change

	Image name varies by --agent-image preset:
	Image name (when pulling preset images, i.e., without --build-local) varies by --agent-image preset:

[github-actions]

Smoke Test Results

✅ GitHub MCP: #1162 test: add chroot escape vector test coverage | #1161 test: add TOCTOU error path coverage for ssl-bump.ts
✅ Playwright: github.com title contains "GitHub"
✅ File Write: /tmp/gh-aw/agent/smoke-test-claude-22964704073.txt created
✅ Bash: File contents verified

Overall: PASS

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

[github-actions]

🏗️ Build Test Suite Results

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

Overall: 0/8 ecosystems passed — ❌ FAIL

---

❌ Error Details

ALL_CLONES_FAILED: All 8 repository clones failed because gh CLI is not authenticated (no GH_TOKEN environment variable available in this sandbox).

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

This affected all ecosystems: Bun, C++, Deno, .NET, Go, Java, Node.js, and Rust. No tests could be executed.

Generated by Build Test Suite for issue #1228 · ◷

[github-actions]

PR titles: test: add workDir tmpfs hiding integration tests | test: add chroot escape vector test coverage
Tests: MCP✅; safeinputs✅; playwright✅; tavily❌; file✅; bash✅; discussion✅; build✅
Overall: FAIL

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

[github-actions]

🤖 Smoke test results for run 22964704136:

Test	Status
GitHub MCP — last 2 merged PRs: #1219 test: add workDir tmpfs hiding integration tests, #1204 chore(deps): bump the all-docs-site-dependencies group	✅
Playwright — github.com title contains "GitHub"	✅
File write — /tmp/gh-aw/agent/smoke-test-copilot-22964704136.txt	✅
Bash verification — file read back successfully	✅

Overall: PASS — authored by @Mossaka, no assignees.

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

[github-actions]

Chroot Version Comparison Results

Runtime	Host Version	Chroot Version	Match?
Python	Python 3.12.12	Python 3.12.3	❌ NO
Node.js	v24.14.0	v20.20.0	❌ NO
Go	go1.22.12	go1.22.12	✅ YES

Result: ❌ Not all tests passed — Python and Node.js versions differ between host and chroot.

Tested by Smoke Chroot for issue #1228