diff --git a/docs/JS-ENGINE.md b/docs/JS-ENGINE.md
index c6ba05b..470692f 100644
--- a/docs/JS-ENGINE.md
+++ b/docs/JS-ENGINE.md
@@ -1,6 +1,5 @@
-# JS Engine Integration (QuickJS)
-
-- Embed QuickJS for safe, deterministic, sandboxed transforms.
-- No network, no filesystem by default; expose only Kompanion tool FFI shims.
-- Use for text filters, parsers, light data munging; scripts under `~/.config/kompanion/js/`.
-- FFI bridge: `js.callTool(name, args)` → JSON-RPC.
+# Optional JavaScript Engine (QuickJS)
+Goal: lightweight scripting for tools and creative transforms without pulling QtQml.
+Design:\n- Link QuickJS as an optional component (BUILD_JS=ON).\n- Expose sandboxed functions: readText(path allowlist), writeJournal(text), httpFetch(allowlist).\n- Per-aspect capability gates via capabilities.json.
+Security:\n- No require() to filesystem; no dynamic dlopen; memory/time limits per eval.\n- Network only via allowlisted httpFetch; inherits Tor proxy if set.
+API sketch:\n- tools/js.eval {code, args} -> result or error; logs to ledger.