[optimization:agents-md-curator] Compress AGENTS.md: fix broken config file paths, dedupe env-var/debug-logging sections vs docs/ENVIRONMENT_VARIABLES.md (~46% t

`github/gh-aw-mcpg`'s `AGENTS.md` is 560 lines / 32,424 bytes (~8,106 tokens), loaded on every agent run. Two sections restate content that is already fully and more accurately documented elsewhere (`docs/ENVIRONMENT_VARIABLES.md`), and the Project Structure file list references 2 non-existent config files. Compressing these sections removes an estimated ~3,772 net tokens (~46.5%) from the file with no loss of operative facts.

**Action:** Assign the linked issue to Copilot (or a maintainer) to apply the prompt below; acceptance check is `AGENTS.md` staying under 200 lines/10 KB and at least 10% smaller in estimated tokens, with no broken paths remaining.

### Ambient context health

| Metric | Value | Target | Status |
|---|---|---|---|
| Lines | 560 | < 200 | ❌ over |
| Bytes | 32,424 | < 10 KB | ❌ over (3.2×) |
| Estimated tokens | 8,106 | — | — |
| Days since last change | 1 | < 90 | ✅ fresh |
| Commits since last change | 39 | — | — |
| Broken referenced paths | 2 genuinely missing (`config_env.go`, `validation.go`) out of a bullet list of files that mostly exist | 0 | ❌ |
| Cross-file conflicts | 0 | 0 | ✅ |
| Duplication with README/CONTRIBUTING | 1 line (README), 12 lines (CONTRIBUTING) | minimal | ⚠️ borderline |

Note on broken paths: of the paths in the `internal/config/` bullet list, `config_env.go` and `validation.go` do not exist anywhere in the repository (verified with a repo-wide file search). The package was actually split differently: the real files are `config_core.go`, `config_stdin.go`, `config_feature.go`, `config_tracing.go`, `gateway_env.go`, `validation_env.go`, `validation_gateway.go`, `validation_rules.go`, `validation_server.go`, `validation_schema.go`, `validation_tracing.go`. `validation_test.go` does exist (1,335 lines) so that specific reference is fine.

The file is large chiefly because of two sections that duplicate `docs/ENVIRONMENT_VARIABLES.md` (a 174-line file that documents every environment variable, precedence order, and script-specific overrides in more detail and more accurately than `AGENTS.md`'s inline copy):
- **Debug Logging** (lines 290-402, 113 lines / 4,885 bytes) repeats logger usage, examples, and `DEBUG=`/`DEBUG_COLORS` controls already covered by `CONTRIBUTING.md`'s "Debug Logging" subsection.
- **Environment Variables** (lines 403-517, 115 lines / 12,534 bytes) is a near-complete inline copy of `docs/ENVIRONMENT_VARIABLES.md`'s ~40 variables, plus file-logging/payload/tools-catalog subsections that duplicate `docs/CONFIGURATION.md`.

### Estimated gain

- Tokens removed (Debug Logging + Environment Variables sections, replaced by compressed pointers): ~4,885 + 12,534 = 17,419 chars of original content
- Tokens added (compressed replacement retaining the highest-value facts + link): ~2,331 chars
- Project Structure bullet edit: net +59 chars to correct the file list (small cost, required for correctness)
- **Net chars removed: ~15,088, i.e. ~3,772 tokens (46.5% of the current 8,106 estimated tokens)**
- **Projected post-change token count: ~4,334** (roughly half the current size)

This issue exists because that percentage is well above the 10% threshold.

### Proposed edits

1. **Project Structure, `internal/config/` bullet (lines 29-33)** — `correct`. Replace the sub-bullets with a file list matching what actually exists in `internal/config/`.
- Evidence: a repository-wide search for `config_env.go` and `validation.go` returns no matches in `github/gh-aw-mcpg`; the real files are `config_core.go`, `config_stdin.go`, `config_feature.go`, `config_tracing.go`, `gateway_env.go`, `validation_env.go`, `validation_gateway.go`, `validation_rules.go`, `validation_server.go`, `validation_schema.go`, `validation_tracing.go`.
- Replacement text (4 sub-bullets):
- `config_core.go` - Core `Config`, `GatewayConfig`, and `ServerConfig` types plus TOML loading
- `config_stdin.go` - JSON stdin structs and stdin-to-internal config conversion
- `config_feature.go`, `config_tracing.go`, `gateway_env.go` - Feature-flag, tracing, and gateway-specific env var config helpers
- `validation_env.go`, `validation_gateway.go`, `validation_rules.go`, `validation_server.go`, `validation_schema.go`, `validation_tracing.go` - Fail-fast field, environment, and schema validation, split by concern

2. **Debug Logging section (lines 290-402)** — `compress`. Keep one canonical code example, the `ForFile()`/`New()` rule, the file-logger note, and the `DEBUG=`/`DEBUG_COLORS=` control examples; drop the second "Examples of good logger declarations" code block (duplicate of the first), the "Logging Categories" bullet list, the naming-convention bullet lists, and the "Key Features"/"When to Use"/"When NOT to Use" bullet lists — these are general advice with no gateway-specific facts an agent must load every run.
- Evidence: `CONTRIBUTING.md`'s "Debug Logging" subsection already carries an equivalent code example, naming convention, and control commands for human contributors; keeping a full duplicate in `AGENTS.md` is repetition within the same repository, and the naming/category bullets are prose, not commands an agent executes.

3. **Environment Variables section (lines 403-517)** — `compress` with a pointer to the existing authoritative doc. Replace the ~40-line inline variable list and the "File Logging"/"Large Payload Handling"/"Understanding the payload.json File"/"Tools Catalog" subsections with a pointer to `docs/ENVIRONMENT_VARIABLES.md` (already more detailed and accurate) plus the handful of variables/facts an agent actually needs on nearly every run.
- Evidence: every one of the ~40 variables listed in `AGENTS.md` (`GITHUB_MCP_SERVER_TOKEN`, `GITHUB_TOKEN`, `GITHUB_PERSONAL_ACCESS_TOKEN`, `GH_TOKEN`, `GITHUB_API_URL`, `GITHUB_SERVER_URL`, `ACTIONS_ID_TOKEN_REQUEST_URL`, `ACTIONS_ID_TOKEN_REQUEST_TOKEN`, and all `MCP_GATEWAY_*` variables) is already present in `docs/ENVIRONMENT_VARIABLES.md` with equal or greater detail (e.g. the doc separates required-for-container vs. optional-local variables and documents script-specific overrides that `AGENTS.md` omits entirely). The log-file list (`mcp-gateway.log`, `gateway.md`, `rpc-messages.jsonl`, `tools.json`) also appears in `docs/CONFIGURATION.md`.
- Replacement text:
- Heading: "## Environment Variables"
- "Full reference (every variable, precedence, and defaults): [docs/ENVIRONMENT_VARIABLES.md](docs/ENVIRONMENT_VARIABLES.md)."
- "Most commonly needed during development:" followed by 6 bullets: `DEBUG`, the GitHub token precedence chain (`GITHUB_MCP_SERVER_TOKEN`/`GITHUB_TOKEN`/`GITHUB_PERSONAL_ACCESS_TOKEN`/`GH_TOKEN`), `MCP_GATEWAY_LOG_DIR` (default `/tmp/gh-aw/mcp-logs`), `MCP_GATEWAY_PAYLOAD_DIR` (default `/tmp/jq-payloads`, with the `{payload_dir}/{sessionID}/{queryID}/payload.json` path pattern), `MCP_GATEWAY_SESSION_TIMEOUT` (default `6h`), `MCP_GATEWAY_GUARDS_MODE` (default `strict`)
- A one-line "Log files" note listing `mcp-gateway.log`, `{serverID}.log`, `gateway.md`, `rpc-messages.jsonl`, `tools.json` with a one-clause description each

### Agentic update prompt

Agent prompt

```
You are editing exactly one file: AGENTS.md at the repository root. Do not touch any other file, and do not create any new root instruction file (AGENTS.md already exists; only edit it).

Before applying any edit below, verify it against the current repository state. If a claim no longer holds (a path now exists, a section was already changed), skip that edit and say so explicitly in your PR description rather than applying it anyway.

Apply these edits in order:

1. In the "Project Structure" section, find the internal/config/ bullet and its sub-bullets (currently listing config_core.go, config_stdin.go, config_env.go/config_feature.go/config_tracing.go, and validation.go/validation_env.go/validation_schema.go, plus validation_test.go). Verify with a directory listing of internal/config/*.go which files actually exist. Replace the sub-bullets so they list only files that actually exist, keeping config_core.go and config_stdin.go as-is, and correctly grouping the remaining feature/tracing/env-helper files and the validation files (there are more validation files than the three currently named -- group them accurately: validation_env.go, validation_gateway.go, validation_rules.go, validation_server.go, validation_schema.go, validation_tracing.go). Keep the validation_test.go bullet only if that file still exists.

2. In the "Debug Logging" section, keep exactly one canonical Go code example showing logger.ForFile() usage (with the Printf/Enabled() pattern), one short paragraph explaining the ForFile() vs New() distinction, the file-logger paragraph (LogInfo/LogWarn/LogError/LogDebug), and the DEBUG=/DEBUG_COLORS= bash control examples. Delete the second, near-duplicate "Examples of good logger declarations" code block, the standalone "Logging Categories" bullet list, the "Category Naming Convention" bullet list, the "Logger Variable Naming Convention" bullet list, and the "Key Features"/"When to Use"/"When NOT to Use" bullet lists. Only remove content that CONTRIBUTING.md's own "Debug Logging" subsection (or this same AGENTS.md section) already states elsewhere -- do not delete facts that appear nowhere else.

3. In the "Environment Variables" section, verify that docs/ENVIRONMENT_VARIABLES.md exists and covers the variables you plan to remove (open it and confirm each variable name you're about to cut from AGENTS.md appears there with equivalent or greater detail). Replace the full variable list plus the "File Logging", "Large Payload Handling", "Understanding the payload.json File", and "Tools Catalog (tools.json)" subsections with a short pointer to docs/ENVIRONMENT_VARIABLES.md, keeping inline only: the DEBUG variable, the GitHub token precedence order, MCP_GATEWAY_LOG_DIR with its default, MCP_GATEWAY_PAYLOAD_DIR with its default and the payload.json path pattern, MCP_GATEWAY_SESSION_TIMEOUT with its default, MCP_GATEWAY_GUARDS_MODE with its default, and a one-line list of the log file names created in the log directory. Do not turn this into a bare link with no inline facts -- keep the specific defaults and the payload path pattern inline since agents need them without an extra file read.

Requirements:
- The edited AGENTS.md must stay under 200 lines and under 10 KB, and must be at least 10% smaller in estimated tokens (characters divided by 4) than the current ~8,106-token file. If verification forces you to skip edits and the reduction falls short of 10%, say so explicitly in the PR description rather than padding the diff.
- Do not rewrite, reformat, or reorder any other section of AGENTS.md. Do not touch the Quick Start, Key Tech, Config Examples, Go Conventions, Testing with Testify, Linting, Test Structure, Common Tasks, Agent Completion Checklist, Error Debugging, Security Notes, SDK Upgrade Process, or Resources sections.
- Open a pull request whose description lists each edit applied (with the evidence that justified it) and explicitly names any edit you skipped and why.
```

### Verification

A reviewer can confirm the result by checking: (1) the byte and line counts of AGENTS.md are both under target (10 KB / 200 lines) and the byte count is at least 10% lower than 32,424; (2) every path in the internal/config/ bullet resolves to a real file; (3) the DEBUG, MCP_GATEWAY_LOG_DIR, MCP_GATEWAY_PAYLOAD_DIR, MCP_GATEWAY_SESSION_TIMEOUT, and MCP_GATEWAY_GUARDS_MODE defaults quoted inline still match docs/ENVIRONMENT_VARIABLES.md; (4) the file no longer contains a second copy of the "Examples of good logger declarations" code block; (5) AGENTS.md and CONTRIBUTING.md still agree on tooling (both point to the same make targets and go test, no new package manager introduced).

### Control Plane

- Correlation ID: 35121692608-322
- Central repository: githubnext/gh-aw-cao
- Control plane run URL: https://github.com/githubnext/gh-aw-cao/actions/runs/35121692608

> Generated by [:compass: AW Optimization / AGENTS.md](https://github.com/githubnext/gh-aw-cao/actions/runs/35122509114) · copilot · auto · 229.6 AIC · ⌖ 17.1 AIC · ⊞ 15.2K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-cao+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-cao%2Foptimization-agents-md-curator%22&type=issues)
> - [x] expires on Oct 16, 2026, 4:53 PM UTC

Start with the root AGENTS.md and inspect docs/ENVIRONMENT_VARIABLES.md plus internal/config/*.go to verify the referenced facts and paths. Compress only the specified Debug Logging and Environment Variables sections, correct the config file list, and confirm AGENTS.md is under 200 lines, under 10 KB, and all quoted defaults and paths remain accurate.

Written by the indexing model from the issue text.