Add architecture review and wiki draft

.agents/decisions/DECISION-20260323-compose-secrets-via-env.md

@@ -0,0 +1,36 @@
+# DECISION-20260323-compose-secrets-via-env
+
+## Context
+- Task/request: harden the target-state stack example so credentials are not stored directly in `temp/cloud.yml`.
+- Impacted files/contracts: `temp/cloud.yml`, deployment/operations practice for target-state infrastructure examples.
+- Why a decision is required now: the repository contained inline credentials in a tracked compose file, which conflicts with the intended security posture and creates avoidable secret-leak risk.
+
+## Options
+1. Keep credentials inline in the compose file
+- Benefits: simplest to run as a standalone example.
+- Risks: secrets leak into git history, reviews, copies, and local machines; encourages unsafe operational practice.
+- Rollout notes: none, but the risk remains permanent once committed.
+
+2. Move credentials to server-side environment variables and keep only placeholders in compose
+- Benefits: aligns the manifest with a safer deployment pattern; keeps tracked config portable across environments; supports secret rotation without editing the compose file.
+- Risks: operators must manage `.env` or equivalent secret injection correctly.
+- Rollout notes: provide an example env file and document that the real `.env` stays on the server and out of version control.
+
+## Decision
+- Selected option: Option 2.
+- Decision owner: repository owner confirmed during task discussion.
+- Date: 2026-03-23.
+- Rationale: the target architecture should model the right operational pattern. Inline secrets in repository-tracked compose files are not acceptable for EVOLV's intended OT/IT deployment posture.
+
+## Consequences
+- Compatibility impact: low; operators now need to supply environment variables when deploying `temp/cloud.yml`.
+- Safety/security impact: improved secret hygiene and lower credential exposure risk.
+- Data/operations impact: deployment requires an accompanying `.env` on the server or explicit `--env-file` usage.
+
+## Implementation Notes
+- Required code/doc updates: replace inline secrets in `temp/cloud.yml`; add `temp/cloud.env.example`; keep the real `.env` untracked on the server.
+- Validation evidence required: inspect compose file for `${...}` placeholders and verify no real credentials remain in tracked files touched by this change.
+
+## Rollback / Migration
+- Rollback strategy: reintroduce inline values, though this is not recommended.
+- Migration/deprecation plan: create a server-local `.env` from `temp/cloud.env.example`, fill in real values, and run compose from that environment.