```

docs(event-flow): enhance user memory documentation, validate functionality, update example
```

[auto-enhanced]

Author: steveseguin

actions/STATE_NODES_EXPLANATION.md

@@ -1,68 +1,72 @@
-# State Nodes in Event Flow System
-
-## How State Nodes Work
-
-State nodes maintain persistent state between message events, acting as intelligent filters/controllers in your event flows.
-
-## Available State Nodes
-
-### 🚦 GATE Control
-- **Purpose**: Acts as an on/off switch for message flow
-- **States**: ALLOW (messages pass) or BLOCK (messages stop)
-- **Control**: Use `setGateState` action to change state
-- **Example**: Block duplicate triggers during OBS scene switches
-
-### 📋 QUEUE (Message Queue)
-- **Purpose**: Buffers messages and processes them sequentially
-- **Config**: maxSize, overflowStrategy (DROP_OLDEST, DROP_NEWEST, DROP_RANDOM)
-- **Note**: Currently requires manual implementation of queue processing
-
-### 🎛️ SEMAPHORE
-- **Purpose**: Limits concurrent operations
-- **Config**: maxCount (how many can run simultaneously)
-- **Use Case**: Limit simultaneous webhook calls or resource-intensive actions
-
-### 🔒 LATCH Memory
-- **Purpose**: Once triggered, stays "on" until manually reset
-- **Config**: resetOnTrigger (boolean)
-- **Use Case**: One-time triggers, first-viewer rewards
-
-### ⏲️ THROTTLE (Rate Limiter)
-- **Purpose**: Limits how often messages can pass through
-- **Config**: intervalMs, maxPerInterval
-- **Use Case**: Prevent spam, rate-limit commands
-
-### 🎬 SEQUENCER
-- **Purpose**: Ensures messages are processed in order
-- **Config**: sequenceField (which field to track)
-- **Use Case**: Process events in exact order
-
-## How to Control State Nodes
-
-State nodes are controlled through specific actions:
-
-1. **setGateState** - Changes a GATE node between ALLOW/BLOCK
-   - Config: `targetNodeId`, `state` (ALLOW or BLOCK)
-
-2. **resetStateNode** - Resets any state node to initial state
-   - Config: `targetNodeId`
-
-## Example Workflow: OBS Scene Switch with Gate
-
-```json
-Trigger (!hello) → GATE → Change Scene → Close Gate → Delay → Switch Back → Open Gate
-```
-
-This prevents multiple !hello commands from triggering while the first is still processing.
-
-## Important Notes
-
-- COUNTER, USERPOOL, ACCUMULATOR nodes are defined but not yet implemented
-- State nodes must be connected properly (fixed in latest update)
-- State persists across messages until explicitly changed or reset
-- Some state nodes (QUEUE) need additional actions for full functionality
-
-## Connection Rules
-State nodes can now:
-- Receive connections FROM: Triggers, Actions, Logic nodes, other State nodes
-- Send connections TO: Actions, Logic nodes, other State nodes
+# State Nodes in Event Flow
+
+State nodes keep information between events in one flow. They are useful when an automation needs to remember whether a gate is open, how many events have happened, whether a rate limit has been reached, or which users have participated.
+
+## Available State Nodes
+
+### Gate
+
+- Holds an `ALLOW` or `BLOCK` value.
+- Passes or stops an event on the normal execution path.
+- Use `Set Gate State` to change it and `Reset State Node` to restore its configured default.
+
+### Counter
+
+- Holds a numeric value and can check it against a target.
+- Use `Set Counter Value`, `Increment Counter`, `Check Counter`, or `Reset State Node`.
+- `Check Counter` adds `counterValue`, `counterTarget`, and `counterRemaining` to the event for downstream templates.
+
+### Rate Limiter
+
+- Tracks recent event timestamps and limits how many events may pass during a configured interval.
+- Use `Reset State Node` to clear only the selected limiter's recent-event history.
+
+### User Memory
+
+- Owns one named, isolated set of unique users.
+- User Memory is a shared resource, not an execution step, so it has no normal input/output ports.
+- `Remember User`, `Forget User`, `Clear All Users`, `Pick Random User`, and `User Is Remembered` select a User Memory node by ID.
+- The generic `Reset State Node` action can also clear the selected User Memory.
+- Users are keyed by platform plus user ID, with username fields used only as a fallback. Events without a usable user identity are ignored.
+- Repeated events from one user update that entry's participation count without creating duplicate draw entries.
+
+See the full [User Memory guide](user-memory-guide.html) for screenshots and participation, eligibility, and prize-draw examples.
+
+## Execution Wires and State References
+
+- Solid teal wires show event execution: which node runs next.
+- Dashed purple links show a shared User Memory reference: which memory an operation reads or changes.
+- A User Memory operation stores the target state node's ID internally. The target can be set from the node properties or by dragging its purple side connector to a User Memory node.
+- Selecting a User Memory highlights the operations linked to it. Deleting the memory warns that those references will be removed.
+
+Gate, Counter, and Rate Limiter nodes remain part of the normal execution path. Their control actions also select the target state node by ID, but those relationships currently do not have the dashed canvas link used by User Memory.
+
+## User Memory Persistence and Reset Scope
+
+A User Memory can last for the current app session or be saved across restarts. Each memory also has independent options to clear:
+
+- Manually from its properties.
+- Through `Clear All Users` or `Reset State Node` in a flow.
+- After a configured period of inactivity.
+- When a stream starts.
+- When a stream stops.
+
+"Clear All Users" means every user in the selected memory only. It does not clear other User Memory nodes or unrelated Event Flow state.
+
+## Example: Unique Prize Draw
+
+```text
+!enter -> Remember User ....> [User Memory: Prize Draw Entrants]
+!draw  -> Pick Random User ..> [User Memory: Prize Draw Entrants]
+!reset -> Clear All Users ...> [User Memory: Prize Draw Entrants]
+```
+
+Use normal role/user checks before `Pick Random User` and `Clear All Users` so only a host or moderator can operate the draw. Enable the draw action's remove-winner option if the same person should not be selected twice.
+
+## Setup Checklist
+
+1. Add and name the state node first.
+2. Add the triggers/actions that will read or change it.
+3. Select the intended state node in every control operation.
+4. Test with at least two users and reset the state between scenarios.
+5. For User Memory, verify persistence and automatic-reset settings before going live.

actions/event-flow-guide.html

@@ -261,6 +261,9 @@ <h2>0. Quick Orientation</h2>
                 <div class="panel">
                     <strong>Event Flow</strong> is a node-based editor. Each line carries a message payload plus a boolean state (<em>true</em> = continue, <em>false</em> = stop). Use <strong>sources</strong> to inject events, <strong>logic nodes</strong> to filter decisions, and <strong>actions</strong> to make things happen (send chat, control overlays, relay messages, etc.).
                 </div>
+                <div class="callout">
+                    Need to remember participants, check later eligibility, run a unique-user draw, or clear one named list? Open the <a href="user-memory-guide.html">User Memory guide</a> for the shared-state model, screenshots, and an importable example.
+                </div>
                 <h3 id="what-is-event-flow">What is this editor?</h3>
                 <p>The Event Flow editor is the “advanced automation” layer for Social Stream Ninja. It sits above the simple popup switches and lets you script your own routing logic. Use it when you need to:</p>
                 <ul>

actions/examples/user-memory-participation-draw.json

@@ -1,6 +1,6 @@
 {
   "name": "User Memory: Participation + Prize Draw",
-  "description": "Remembers unique !enter users, checks later ? messages, picks a random entrant, and clears only this draw's memory.",
+  "description": "Remembers unique !enter users, checks later ? messages, and gives moderators protected draw/reset commands for this memory only.",
   "active": true,
   "nodes": [
     {
@@ -84,13 +84,22 @@
       "type": "action",
       "actionType": "pickRandomUser",
       "label": "Pick random entrant",
-      "x": 260,
+      "x": 450,
       "y": 560,
       "config": {
         "targetNodeId": "state_prize_draw",
         "removeSelected": true
       }
     },
+    {
+      "id": "logic_draw_authorized",
+      "type": "logic",
+      "logicType": "AND",
+      "label": "Draw command and moderator",
+      "x": 260,
+      "y": 560,
+      "config": {}
+    },
     {
       "id": "trigger_reset_draw",
       "type": "trigger",
@@ -107,12 +116,32 @@
       "type": "action",
       "actionType": "clearUserMemory",
       "label": "Clear all draw entrants",
-      "x": 260,
+      "x": 450,
       "y": 730,
       "config": {
         "targetNodeId": "state_prize_draw"
       }
     },
+    {
+      "id": "logic_reset_authorized",
+      "type": "logic",
+      "logicType": "AND",
+      "label": "Reset command and moderator",
+      "x": 260,
+      "y": 730,
+      "config": {}
+    },
+    {
+      "id": "trigger_moderator",
+      "type": "trigger",
+      "triggerType": "userRole",
+      "label": "User is a moderator",
+      "x": 20,
+      "y": 900,
+      "config": {
+        "role": "mod"
+      }
+    },
     {
       "id": "state_prize_draw",
       "type": "state",
@@ -148,13 +177,29 @@
     },
     {
       "from": "trigger_draw",
+      "to": "logic_draw_authorized"
+    },
+    {
+      "from": "trigger_moderator",
+      "to": "logic_draw_authorized"
+    },
+    {
+      "from": "logic_draw_authorized",
       "to": "action_pick_winner"
     },
     {
       "from": "trigger_reset_draw",
+      "to": "logic_reset_authorized"
+    },
+    {
+      "from": "trigger_moderator",
+      "to": "logic_reset_authorized"
+    },
+    {
+      "from": "logic_reset_authorized",
       "to": "action_clear_draw"
     }
   ],
-  "version": "1.0.0",
+  "version": "1.1.0",
   "exportedBy": "Social Stream Event Flow System"
 }

actions/state-nodes-guide.html

@@ -186,40 +186,42 @@
         <header>
             <div class="badge">Event Flow System</div>
             <h1>State Nodes Playbook</h1>
-            <p>State nodes give Social Stream Ninja memory. Use them to build cooldowns, toggles, counters, and throttles that keep automations predictable. This guide breaks the topic into focused mini-guides with examples and troubleshooting tips.</p>
+            <p>State nodes give Social Stream Ninja memory. Use them to build cooldowns, toggles, counters, throttles, participant lists, and prize draws that keep automations predictable.</p>
             <nav>
                 <a href="#overview">Overview</a>
                 <a href="#switch">On/Off Switch</a>
                 <a href="#counter">Counter</a>
                 <a href="#throttle">Rate Limiter</a>
+                <a href="#user-memory">User Memory</a>
                 <a href="#recipes">Problem Kits</a>
                 <a href="#troubleshooting">Troubleshooting</a>
             </nav>
         </header>
         <div class="content">
             <section id="overview">
                 <h2>01 · Quick Orientation</h2>
-                <p>Every State node has two halves:</p>
+                <p>State tools have an object that owns the value and operations that read or change it:</p>
                 <div class="grid">
                     <div class="card">
                         <h4>State Node</h4>
                         <ul>
                             <li>Lives on the canvas.</li>
-                            <li>Holds the value (ON/OFF, count, timestamps).</li>
-                            <li>Runs for every message that enters the node.</li>
+                            <li>Holds the value (ON/OFF, count, timestamps, or users).</li>
+                            <li>Gate, Counter, and Rate Limiter can run in the normal event path.</li>
+                            <li>User Memory is a shared hub referenced by other nodes.</li>
                         </ul>
                     </div>
                     <div class="card">
                         <h4>State Action</h4>
                         <ul>
                             <li>Placed downstream.</li>
-                            <li>Changes the stored value (set ON, add +1, reset, etc.).</li>
+                            <li>Reads or changes the stored value (set ON, add +1, remember, draw, reset, etc.).</li>
                             <li>Can live anywhere in the flow—just pick the matching node name.</li>
                         </ul>
                     </div>
                 </div>
                 <div class="panel info">
-                    <strong>Remember:</strong> Add the State node first, give it a unique name, then wire the matching action node. Without the base node, Set/Increment/Reset actions have nothing to talk to.
+                    <strong>Remember:</strong> Add the State node first, give it a unique name, then select it from each matching operation. Without the base node, state actions have nothing to update.
                 </div>
             </section>
 
@@ -316,8 +318,42 @@ <h4>Configuration</h4>
                 </div>
             </section>
 
+            <section id="user-memory">
+                <h2>05 · User Memory</h2>
+                <p>User Memory owns one named list of unique people. Remember users when they participate, check that list on later messages, remove a person, choose a random winner, or clear only that list.</p>
+                <div class="grid">
+                    <div class="card">
+                        <h4>Best for</h4>
+                        <ul>
+                            <li>Gift-based or badge-based eligibility.</li>
+                            <li>Remembering viewers who liked, entered, or participated.</li>
+                            <li>Unique-entry prize draws.</li>
+                            <li>Separate lists for separate campaigns.</li>
+                        </ul>
+                    </div>
+                    <div class="card">
+                        <h4>Operations</h4>
+                        <ul>
+                            <li><code>Remember User</code> and <code>Forget User</code>.</li>
+                            <li><code>User Is Remembered</code>.</li>
+                            <li><code>Pick Random User</code>.</li>
+                            <li><code>Clear All Users</code> or <code>Reset State Node</code>.</li>
+                        </ul>
+                    </div>
+                </div>
+                <div class="diagram">
+Participation Trigger ──▶ Remember User ······▶ User Memory: Entrants
+Draw Command ───────────▶ Pick Random User ···▶ User Memory: Entrants
+Reset Command ──────────▶ Clear All Users ·····▶ User Memory: Entrants
+                </div>
+                <p>Solid teal wires carry events. Dashed purple links show which shared memory an operation uses. Each User Memory has its own count, persistence mode, and reset policy, so clearing one list does not affect another.</p>
+                <div class="panel success">
+                    See the dedicated <a href="user-memory-guide.html">User Memory guide</a> for reviewed screenshots, a downloadable draw flow, TikTok eligibility, participation examples, and reset details.
+                </div>
+            </section>
+
             <section id="recipes">
-                <h2>05 · Problem Kits</h2>
+                <h2>06 · Problem Kits</h2>
                 <p>Pick a scenario and follow the steps.</p>
                 <div class="grid">
                     <div class="card">
@@ -362,7 +398,7 @@ <h3>Example Flow Charts</h3>
             </section>
 
             <section id="troubleshooting">
-                <h2>06 · Troubleshooting & FAQ</h2>
+                <h2>07 · Troubleshooting & FAQ</h2>
                 <table>
                     <thead>
                         <tr>
@@ -387,6 +423,11 @@ <h2>06 · Troubleshooting & FAQ</h2>
                             <td>Window too strict or leftover state from testing.</td>
                             <td>Relax the limit and drop a Reset State Node action before retesting.</td>
                         </tr>
+                        <tr>
+                            <td>A User Memory operation has no dashed link.</td>
+                            <td>No target memory is selected.</td>
+                            <td>Choose the named memory in the operation's properties or drag its purple side connector onto the memory.</td>
+                        </tr>
                         <tr>
                             <td>Guide buttons don’t open.</td>
                             <td>Running inside the extension without web_accessible resources updated.</td>
@@ -404,7 +445,7 @@ <h3>Testing Checklist</h3>
             </section>
 
             <section>
-                <h2>07 · Next Steps</h2>
+                <h2>08 · Next Steps</h2>
                 <p>Combine state nodes with the rest of the Event Flow toolkit:</p>
                 <ul>
                     <li>Use logic gates (AND/OR/NOT) before a switch to decide who can toggle it.</li>