feat: agent remote configuration (overlay, apply modes, safeguards)

AGENTS.md

@@ -114,6 +114,11 @@ change here must keep working with them.
   and `_policy_data_digest`.
 - **The agent never computes artifact digests.** It passes each evaluation's policy
   directory, input and policy data through to the API, which canonicalises and hashes them.
+- **Evidence identity.** `policy-manager`'s `newEvidence` seed is every evidence stream's UUID, and plugins in the
+  field compute it. Never change it. The golden test in `policy-manager/evidence_seed_test.go` pins the UUIDs.
+- **Plugin library version.** `internal/pluginlib` reads the agent library a plugin binary was built with from its
+  Go build info. The config report lists it per plugin (`plugins[].lib-version`) as diagnostics only; nothing is
+  gated on it.
 - **Storage failure doesn't drop evidence.** If artifact storage fails, the evidence is still
   sent, without digests.
 - **OCI policy bundles.** The agent evaluates the extracted `policies/` subdirectory, and that

Makefile

@@ -38,7 +38,7 @@ proto-gen: ## Generate objects from proto definitions
 ##@ Test
 .PHONY: test
 test:  ## Run tests
-	@if ! go test ./... -coverprofile cover.out -v; then \
+	@if ! go test ./... -race -coverprofile cover.out -v; then \
 		$(WARN) "Tests failed"; \
 		exit 1; \
 	fi ; \

README.md

@@ -92,6 +92,18 @@ The API auth settings follow the same rule, so `api.auth.client_id` and `api.aut
 `CCF_API_AUTH_CLIENT_ID` and `CCF_API_AUTH_CLIENT_SECRET`. These values must be configured together; setting only one
 will fail agent startup validation. The `client_id` value must be a valid UUID.
 
+Values that come from `CCF_PLUGINS_*` variables are masked in the configuration reports the agent sends to the API,
+as are secret-like keys and values (see [configuration](./docs/configuration.md#envname-placeholders)).
+Plugins never receive `CCF_API_AUTH_*` variables.
+
+### Remote configuration and state
+
+With `api.auth` credentials the agent reports its configuration to the API. With `remote_config.mode` set to
+`apply_safe` or `apply_all` it also applies a configuration overlay stored there, including `${env:NAME}` placeholders
+in plugin config; the default mode, `report`, never fetches or applies one. Each instance keeps a stable ID and a cache in a state directory (`--state-dir` / `CCF_STATE_DIR`;
+`--instance-id` / `CCF_INSTANCE_ID`). See [configuration](./docs/configuration.md#remote-configuration) and
+[ADR 0003](./docs/adr/0003-remote-config-overlay.md).
+
 ## Usage
 
 To run the agent, you must first build the agent, and then run it with the `agent` command. It is recommended,