diff --git a/docs/ISSUES.md b/docs/ISSUES.md
new file mode 100644
index 0000000..fb81599
--- /dev/null
+++ b/docs/ISSUES.md
@@ -0,0 +1,80 @@
+# Open Issues — EVOLV Codebase
+
+Issues identified during codebase scan (2026-03-12). Create these on Gitea when ready.
+
+---
+
+## Issue 1: Restore diffuser node implementation
+
+**Labels:** `enhancement`, `node`
+**Priority:** Medium
+
+The `nodes/diffuser/` directory contains only `.git`, `LICENSE`, and `README.md` — no implementation. There was a previous experimental version. Needs:
+
+- Retrieve original diffuser logic from user/backup
+- Rebuild to current three-layer architecture (wrapper `.js` + `src/nodeClass.js` + `src/specificClass.js`)
+- Use `require('generalFunctions')` barrel imports
+- Add config JSON in `generalFunctions/src/configs/diffuser.json`
+- Register under category `'EVOLV'` with appropriate S88 color
+- Add tests
+
+**Blocked on:** User providing original diffuser logic/requirements.
+
+---
+
+## Issue 2: Relocate prediction/ML modules to external service
+
+**Labels:** `enhancement`, `architecture`
+**Priority:** Medium
+
+TensorFlow-based influent prediction code was removed from monster node (was broken/incomplete). The prediction functionality needs a new home:
+
+- LSTM model for 24-hour flow prediction based on precipitation data
+- Standardization constants: hours `(mean=11.504, std=6.922)`, precipitation `(mean=0.090, std=0.439)`, response `(mean=1188.01, std=1024.19)`
+- Model was served from `http://127.0.0.1:1880/generalFunctions/datasets/lstmData/tfjs_model/`
+- Consider: separate microservice, Python-based inference, or ONNX runtime
+- Monster node should accept predictions via `model_prediction` message topic from external service
+
+**Related files removed:** `monster_class.js` methods `get_model_prediction()`, `model_loader()`
+
+---
+
+## Issue 3: Modernize monster node to three-layer architecture
+
+**Labels:** `refactor`, `node`
+**Priority:** Low
+
+Monster node uses old-style structure (`dependencies/monster/` instead of `src/`). Should be refactored:
+
+- Move `dependencies/monster/monster_class.js` → `src/specificClass.js`
+- Create `src/nodeClass.js` adapter (extract from `monster.js`)
+- Slim down `monster.js` to standard wrapper pattern
+- Move `monsterConfig.json` → `generalFunctions/src/configs/monster.json`
+- Remove `modelLoader.js` (TF dependency removed)
+- Add unit tests
+
+**Note:** monster_class.js is ~500 lines of domain logic. Keep sampling_program(), aggregation, AQUON integration intact.
+
+---
+
+## Issue 4: Clean up inline test/demo code in specificClass files
+
+**Labels:** `cleanup`
+**Priority:** Low
+
+Several specificClass files have test/demo code after `module.exports`:
+
+- `pumpingStation/src/specificClass.js` (lines 478-697): Demo code guarded with `require.main === module` — acceptable but could move to `test/` or `examples/`
+- `machineGroupControl/src/specificClass.js` (lines 969-1158): Block-commented test code with `makeMachines()` — dead code, could be removed or moved to test file
+
+---
+
+## Issue 5: DashboardAPI node improvements
+
+**Labels:** `enhancement`, `security`
+**Priority:** Low
+
+- Bearer token now relies on `GRAFANA_TOKEN` env var (hardcoded token was removed for security)
+- Ensure deployment docs mention setting `GRAFANA_TOKEN`
+- `dashboardapi_class.js` still has `console.log` calls (lines 154, 178) — should use logger
+- Node doesn't follow three-layer architecture (older style)