AWF config specs and schemas not fully consumed by gh-aw agents

[lpcox]

Problem

gh-aw agents (e.g. the schema-sync workflow) are not picking up all AWF configuration options when generating PRs or compiling workflows. For example, PR github/gh-aw-firewall#2753 identified three apiProxy fields present in the JSON Schema but missing from the spec's CLI mapping table.

This suggests the gh-aw compilation/validation pipeline may not be referencing the full set of AWF specification documents.

AWF Specs and Schemas (canonical sources)

All live in github/gh-aw-firewall:

Normative Specification

• docs/awf-config-spec.md — W3C-style configuration specification (processing model, precedence, CLI mapping, environment merge semantics, credential isolation)

JSON Schemas

• docs/awf-config.schema.json — Authoritative JSON Schema for .awf.json/.awf.yml config files (used by IDEs for validation)
• src/awf-config-schema.json — Source-of-truth schema used by the AWF CLI at runtime (kept in sync with docs/ version via CI test)
• schemas/audit.schema.json — Schema for firewall audit log output
• schemas/token-usage.schema.json — Schema for token usage reports

Supporting Documentation

• docs/environment.md — Environment variable configuration guide
• docs/authentication-architecture.md — Credential isolation architecture
• schemas/README.md — Schema directory overview

Key fields that were missed

These apiProxy options exist in the schema but were not reflected in the spec's §5 CLI mapping until manually fixed (PR #2759):

Config path	CLI flag
apiProxy.anthropicAutoCache	--anthropic-auto-cache
apiProxy.anthropicCacheTailTtl	--anthropic-cache-tail-ttl
apiProxy.models	config-only (model alias rewriting)

Suggestion

Consider having the gh-aw compile/validate pipeline reference docs/awf-config.schema.json to ensure all config properties are known and mapped. This would catch drift between what AWF supports and what gh-aw generates.

[lpcox]

@pelikhan

[pelikhan]

@copilot generate a spec file that stores this informations so that the agent learns to look for thos info. Add comment in the awf_config.go cross reference