Add architecture review and wiki draft

.agents/decisions/DECISION-20260323-architecture-layering-resilience-and-config-authority.md

@@ -0,0 +1,36 @@
+# DECISION-20260323-architecture-layering-resilience-and-config-authority
+
+## Context
+- Task/request: refine the EVOLV architecture baseline using the current stack drawings and owner guidance.
+- Impacted files/contracts: architecture documentation, future wiki structure, telemetry/storage strategy, security boundaries, and configuration authority assumptions.
+- Why a decision is required now: the architecture can no longer stay at a generic "Node-RED plus cloud" level; several operating principles were clarified by the owner and need to be treated as architectural defaults.
+
+## Options
+1. Keep the architecture intentionally broad and tool-centric
+- Benefits: fewer early commitments.
+- Risks: blurred boundaries for resilience, data ownership, and security; easier to drift into contradictory implementations.
+- Rollout notes: wiki remains descriptive but not decision-shaping.
+
+2. Adopt explicit defaults for resilience, API boundary, telemetry layering, and configuration authority
+- Benefits: clearer target operating model; easier to design stack services and wiki pages consistently; aligns diagrams with intended operational behavior.
+- Risks: some assumptions may outpace current implementation and therefore create an architecture debt backlog.
+- Rollout notes: document gaps clearly and treat incomplete systems as planned workstreams rather than pretending they already exist.
+
+## Decision
+- Selected option: Option 2.
+- Decision owner: repository owner confirmed during architecture review.
+- Date: 2026-03-23.
+- Rationale: the owner clarified concrete architecture goals that materially affect security, resilience, and platform structure. The documentation should encode those as defaults instead of leaving them implicit.
+
+## Consequences
+- Compatibility impact: low immediate code impact, but future implementations should align to these defaults.
+- Safety/security impact: improved boundary clarity by making central the integration entry point and keeping edge protected behind site/central mediation.
+- Data/operations impact: multi-level InfluxDB and smart-storage behavior become first-class design concerns; `tagcodering` becomes the intended configuration backbone.
+
+## Implementation Notes
+- Required code/doc updates: update the architecture review doc, add visual wiki-ready diagrams, and track follow-up work for incomplete `tagcodering` integration and telemetry policy design.
+- Validation evidence required: architecture docs reflect the agreed principles and diagrams; no contradiction with current repo evidence for implemented components.
+
+## Rollback / Migration
+- Rollback strategy: return to a generic descriptive architecture document without explicit defaults.
+- Migration/deprecation plan: implement these principles incrementally, starting with configuration authority, telemetry policy, and site/central API boundaries.

.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.

.agents/improvements/IMPROVEMENTS_BACKLOG.md

@@ -22,3 +22,6 @@ Lifecycle:
 | IMP-20260219-022 | 2026-02-19 | generalFunctions/outliers | `DynamicClusterDeviation.update()` emits verbose `console.log` traces on each call with no log-level guard, unsafe for production telemetry volume. | `nodes/generalFunctions/src/outliers/outlierDetection.js:7` | open |
 | IMP-20260224-006 | 2026-02-24 | rotatingMachine prediction fallback | When only one pressure side is available, predictor uses absolute pressure as surrogate differential, which can materially bias flow prediction under varying suction/discharge conditions. | `nodes/rotatingMachine/src/specificClass.js:573`, `nodes/rotatingMachine/src/specificClass.js:588` | open |
 | IMP-20260224-012 | 2026-02-24 | cross-node unit architecture | Canonical unit-anchor strategy is implemented in rotatingMachine plus phase-1 controllers (`machineGroupControl`, `pumpingStation`, `valve`, `valveGroupControl`); continue rollout to remaining nodes so all runtime paths use canonical storage + explicit ingress/egress units. | `nodes/machineGroupControl/src/specificClass.js:42`, `nodes/pumpingStation/src/specificClass.js:48`, `nodes/valve/src/specificClass.js:87`, `nodes/valveGroupControl/src/specificClass.js:78` | open |
+| IMP-20260323-001 | 2026-03-23 | architecture/security | `temp/cloud.yml` stores environment credentials directly in a repository-tracked target-state stack example; replace with env placeholders/secret injection and split illustrative architecture from deployable manifests. | `temp/cloud.yml:1` | open |
+| IMP-20260323-002 | 2026-03-23 | architecture/configuration | Intended database-backed configuration authority (`tagcodering`) is not yet visibly integrated as the primary runtime config backbone in this repository; define access pattern, schema ownership, and rollout path for edge/site/central consumers. | `architecture/stack-architecture-review.md:1` | open |
+| IMP-20260323-003 | 2026-03-23 | architecture/telemetry | Multi-level smart-storage strategy is a stated architecture goal, but signal classes, reconstruction guarantees, and authoritative-layer rules are not yet formalized; define telemetry policy before broad deployment. | `architecture/stack-architecture-review.md:1` | open |