# AGENTS.md — Configuration Tier Guidelines

**Scope:** `config/` directory  
**Responsibility:** Declarative GitOps state for Zyphon Gateway  

---

## 1. Module Purpose & Boundaries
This module holds the declarative, filesystem-based single source of truth for the entire Zyphon Gateway cluster. It replaces all operational database configurations.

## 2. Key Files
- [`applications.yaml`](applications.yaml): Client application definitions, pre-computed SHA-256 API key hashes, allowed channels, and rate limits.
- [`providers.yaml`](providers.yaml): Provider adapter configurations with dynamic `${ENV_VAR}` secret pointers.
- [`routing.yaml`](routing.yaml): Channel primary routes, fallback provider cascades, timeout deadlines, and circuit breaker thresholds.
- [`zyphon.yaml`](zyphon.yaml): Server network host/port bindings and NDJSON log settings.

## 3. Local Operational Rules
1. **Never Commit Raw Secrets**:
   - Provider keys, auth tokens, and passwords must **always** be specified as environment variable placeholders (e.g. `${SENDGRID_API_KEY}`, `${TWILIO_AUTH_TOKEN}`).
2. **Fail-Closed Channel Permissions**:
   - Every client application must have an explicit `allowedChannels` whitelist array. Wildcard entries (`"*"`) are strictly prohibited and rejected by schema validation.
3. **Pre-Compute Key Hashes**:
   - In `applications.yaml`, the `apiKeyHash` must be a 64-character lowercase hex string representing the SHA-256 digest of the client secret. Raw tokens must never be written to this file.
4. **Preserve Valid YAML Syntax**:
   - Because the gateway uses an inotify hot-reloader, syntax errors will trigger reload failures and alert logs. Always test YAML syntax before committing.

## 4. Relevant Documentation
- Architectural Rules: [`docs/RULES.md`](../docs/RULES.md)
- Configuration Schemas: [`docs/DESIGN.md#2-declarative-filesystem-configuration-schemas`](../docs/DESIGN.md)