docs: document environment field and agent env-scoped config behavior

- PROTOCOL.md: document the new ApplicationConfig.environment field in
  the envelope schema; explain that the server derives env from the
  JWT claim at registration so same applicationId across environments
  gets distinct configs; note both sides tolerate unknown fields; add
  cameleer.agent.environment to the agent properties table; clarify
  the new WARN-on-unset behavior in the registration payload notes.
- AGENTS.md / CLAUDE.md: refreshed GitNexus index stats.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -1,7 +1,7 @@
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer** (4446 symbols, 12751 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer** (4461 symbols, 12794 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

CLAUDE.md

@@ -56,7 +56,7 @@ Run commands: see `docs/running.md`. CI/CD details: see `docs/ci-cd.md`.
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer** (4446 symbols, 12751 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer** (4461 symbols, 12794 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
 

cameleer-common/PROTOCOL.md

@@ -71,6 +71,7 @@ Base URL configured via `cameleer.agent.export.endpoint` (e.g., `http://localhos
 {
   "config": {
     "application": "sample-app",
+    "environment": "development",
     "version": 5,
     "updatedAt": "2026-04-16T17:25:24.238571Z",
     "engineLevel": "REGULAR",
@@ -90,7 +91,7 @@ Base URL configured via `cameleer.agent.export.endpoint` (e.g., `http://localhos
 
 | Field | Type | Description |
 |-------|------|-------------|
-| `config` | `ApplicationConfig` | The per-application config document |
+| `config` | `ApplicationConfig` | The per-application config document. Includes an `environment` field identifying which environment this config applies to; the server derives the value from the agent's JWT env claim at fetch time, so two agents with the same `applicationId` in different environments receive different configs. |
 | `globalSensitiveKeys` | `List<String>`, nullable | Server-wide defaults (informational; not applied directly) |
 | `mergedSensitiveKeys` | `List<String>`, nullable | `globalSensitiveKeys` merged with any per-app overrides — this is what the agent applies for masking |
 
@@ -187,7 +188,7 @@ On failure: `{"status": "FAILURE", "message": "Invalid signature"}`
 
 - `instanceId`: unique identifier for this agent instance. Computed as `{hostname}-{pid}`, or overridden via `cameleer.agent.instanceid`. **Must be unique per JVM** — in Docker/K8s where PID is always 1, the hostname (pod name) ensures uniqueness across replicas.
 - `applicationId`: application identifier shared by all instances of the same app (from `cameleer.agent.application`, defaults to "default")
-- `environmentId`: environment identifier (from `cameleer.agent.environment`, defaults to "default"). Groups agents by deployment environment (e.g., "dev", "staging", "prod"). Also sent in heartbeats to enable server auto-recovery after restart.
+- `environmentId`: environment identifier (from `cameleer.agent.environment`). Groups agents by deployment environment (e.g., "development", "staging", "production"). Also sent in heartbeats to enable server auto-recovery after restart. The server persists this on the agent's JWT claims at registration and uses it to return the correct per-environment `ApplicationConfig` on subsequent fetches — so the same `applicationId` can have different configs per environment. If the agent cannot resolve `cameleer.agent.environment` from a system property or environment variable, it logs a `WARN` at startup and registers as `"default"`; operators should set this explicitly to avoid config cross-contamination.
 - `capabilities`: object mapping capability names to boolean values. `replay` only `true` if `cameleer.agent.replay.enabled=true`. `routeControl` only `true` if `cameleer.agent.routecontrol.enabled=true`. `logForwarding` is `true` if a supported logging framework (Logback or Log4j2) was detected and the appender was installed.
 - `routeIds`: list of Camel route IDs discovered at startup
 
@@ -209,7 +210,7 @@ On failure: `{"status": "FAILURE", "message": "Invalid signature"}`
 - Serialization: Jackson with `JavaTimeModule`
 - `Instant` fields serialized as ISO-8601 strings
 - Null fields omitted (`@JsonInclude(NON_NULL)`)
-- The server MUST accept unknown fields for forward compatibility (`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES = false`)
+- Both server and agent MUST accept unknown fields for forward compatibility (`DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES = false`, or per-class `@JsonIgnoreProperties(ignoreUnknown = true)`). This lets either side add fields to shared models (e.g., `ApplicationConfig`) without requiring lockstep upgrades.
 - Transport model classes: `com.cameleer.common.model.*` (ExecutionChunk, FlatProcessorRecord, MetricsSnapshot, ExchangeSnapshot) and `com.cameleer.common.graph.*` (RouteGraph, RouteNode, RouteEdge)
 - Legacy model classes (retained, not used for transport): RouteExecution, ProcessorExecution
 - See `DIAGRAMS.md` for the full RouteGraph/RouteNode/RouteEdge schema
@@ -222,6 +223,7 @@ On failure: `{"status": "FAILURE", "message": "Invalid signature"}`
 | `cameleer.agent.export.endpoint` | — | Server base URL (e.g., `http://localhost:8081`) |
 | `cameleer.agent.instanceid` | — | Optional instance identifier (overrides auto-computed `{hostname}-{pid}`) |
 | `cameleer.agent.application` | `default` | Application identifier shared by all instances of the same app |
+| `cameleer.agent.environment` | `default` (with `WARN`) | Environment identifier used for env-scoped config lookup (e.g., `development`, `staging`, `production`). If unset, the agent emits a `WARN` at startup and registers as `"default"`. Also surfaced in the startup report and the `AGENT_STARTED` event. |
 | `cameleer.agent.engine.level` | `REGULAR` | Engine level: NONE, MINIMAL, REGULAR, COMPLETE |
 | `cameleer.agent.replay.enabled` | `false` | Enable replay capability (must be explicit opt-in) |
 | `cameleer.agent.routecontrol.enabled` | `false` | Enable route control capability (start/stop/suspend/resume routes via SSE) |