Doc: firewall-audit-logs artifact name not documented for downstream consumers

[lpcox]

Problem

Downstream repositories that write custom token analysis or audit workflows using gh run download directly need to know the correct artifact name for firewall logs. This name (firewall-audit-logs) is not documented in the artifact naming compatibility guide or anywhere discoverable by workflow authors.

What happened

In gh-aw-firewall, we had 4 token analysis workflows (copilot-token-usage-analyzer, claude-token-usage-analyzer, copilot-token-optimizer, claude-token-optimizer) that were downloading agent-artifacts to find token-usage.jsonl. This name was wrong — the data lives in the firewall-audit-logs artifact under logs/api-proxy-logs/token-usage.jsonl. The result was that daily token usage reports silently reported "no data found" for all workflows.

Fix: gh-aw-firewall#1883

Why this is confusing

1. gh aw logs handles it correctly — The CLI knows to download firewall-audit-logs (see pkg/cli/logs_artifact_set.go, pkg/constants/constants.go). Workflows that use gh aw logs (like copilot-token-audit and copilot-token-optimizer in this repo) work fine.

2. The artifact naming compatibility doc only covers single-file artifacts — scratchpad/artifact-naming-compatibility.md documents aw-info, safe-output, etc., but does not mention firewall-audit-logs or its structure.

3. Historical naming is misleading — The CHANGELOG mentions "unified agent-artifacts" and gh aw logs has legacy compat for agent-artifacts → agent. A downstream author might reasonably assume agent-artifacts contains all workflow data including token logs.

4. The firewall-audit-logs split is not documented — The changeset (patch-upload-firewall-audit-logs-artifact.md) describes the split, but this is internal-only — downstream repos don't see changesets.

Artifact name reference (for documentation)

From pkg/constants/constants.go:

const FirewallAuditArtifactName = "firewall-audit-logs"

The artifact contains:

firewall-audit-logs/
├── logs/
│   ├── api-proxy-logs/
│   │   └── token-usage.jsonl    ← token usage data
│   └── squid-logs/
│       └── access.log           ← network policy log
└── audit/
    └── audit.jsonl              ← firewall audit trail

Suggestion

One or more of:

1. Document artifact names — Add firewall-audit-logs (and its directory structure) to the artifact naming guide or a new "Artifact Reference" doc page.

2. Add to the report prompt — The report.md and create-agentic-workflow.md prompts guide workflow creation. When a workflow needs token data, the prompt could recommend using gh aw logs --json instead of gh run download directly.

3. Create a shared component — A shared/token-data.md component that pre-downloads token data from recent runs using the correct artifact name, so downstream workflows don't need to know the implementation detail.

Impact

Any repository using gh-aw that writes custom analysis workflows (not using gh aw logs) and needs access to token usage data or firewall audit logs will hit this. The failure mode is silent — data is simply missing with no error.