@hera-al/server 1.6.12 → 1.6.13

package/bundled/plasma/SKILL.md

@@ -0,0 +1,1417 @@
+---
+name: plasma
+description: Event-sourced dynamic UI system for AI-generated interactive interfaces with HTML/CSS/JS
+user-invocable: true
+command-dispatch: true
+---
+
+# PLASMA — Event-Sourced Dynamic UI System v2
+
+**Plasma** is Hera's Dynamic UI system that allows you to generate and control fully custom HTML/CSS/JS interfaces on connected nodes (ElectroNode) with complete change history.
+
+Unlike template-based UI systems, Plasma gives you complete freedom to create any interface using standard web technologies, external libraries (Three.js, D3.js, Chart.js), and your own custom code.
+
+---
+
+## 🤖 Agent Usage Guidelines
+
+**IMPORTANT**: You (the agent) call these tools based on the user's natural language requests. The user NEVER types tool calls directly.
+
+### Prerequisite: Verify Plasma-Capable Nodes
+
+Before using ANY Plasma or Dynamic UI tool, you MUST call `dynamic_ui_list_nodes` to check if there are connected nodes with `plasma` capability. If no nodes are found, inform the user that they need to connect an ElectroNode with the Plasma capability enabled. Do NOT attempt to call `plasma_create`, `plasma_mutate`, `plasma_load`, or `dynamic_ui_render`/`dynamic_ui_update` without a Plasma-capable node.
+
+### When to Use Which Tool
+
+| User Says | You Do |
+|-----------|--------|
+| "Create a form for customers" | Call `plasma_create` with appropriate HTML/CSS/JS |
+| "Build a dashboard" | Call `plasma_create` with dashboard layout |
+| "Make a calculator app" | Call `plasma_create` with calculator UI |
+| "Add validation to the form" | Call `plasma_mutate` with validation JS |
+| "Change the button color to blue" | Call `plasma_mutate` with color change JS |
+| "Fix the layout" | Call `plasma_mutate` with layout fix JS |
+| "Add a cancel button" | Call `plasma_mutate` with new button JS |
+| "Show me the customer form" | Call `plasma_load` with organism name |
+| "Open the dashboard" | Call `plasma_load` with organism name |
+| "Launch the calculator" | Call `plasma_load` with organism name |
+| "What apps do I have?" | Call `plasma_list` |
+| "List my organisms" | Call `plasma_list` |
+| "Show my UIs" | Call `plasma_list` |
+| "Delete the old form" | Call `plasma_delete` with organism name |
+| "Remove the test app" | Call `plasma_delete` with organism name |
+| "What's in the form right now?" | Call `dynamic_ui_query` with JS to read values |
+| "Read the current data from the app" | Call `dynamic_ui_query` with JS expression |
+
+### Discovery Flow
+
+When the user asks to load/open an app but you're not sure which one:
+
+1. Call `plasma_list` to see available organisms
+2. Check folder names (BASIC convention: descriptive, a-zA-Z0-9_)
+3. If uncertain, read manifest.yaml frontmatter (name + description)
+4. Select best match or ask user to clarify
+5. Call `plasma_load` with selected organism
+
+**Example**:
+```
+User: "Show me the form"
+You: [Call plasma_list]
+     [See: customer_form, invoice_form, contact_form]
+     [If ambiguous: ask "Which form? I have customer_form, invoice_form, and contact_form"]
+     [If clear match: call plasma_load({name: "customer_form", node_id: ...})]
+```
+
+### Naming Organisms
+
+When creating organisms, generate descriptive names following BASIC convention:
+- **Format**: a-zA-Z0-9_ only, max 4 words
+- **Style**: snake_case preferred
+- **Descriptive**: Name reflects content
+
+**Good names**: `customer_form`, `sales_dashboard`, `task_manager`, `chat_ui`
+**Bad names**: `form1`, `app`, `my-form`, `very_long_descriptive_name_here`
+
+### Response Style
+
+After calling tools, respond to the user in natural language:
+
+❌ **Bad**: "I called plasma_create with parameters {name: 'customer_form', ...}"
+✅ **Good**: "I've created a customer entry form with name and email fields. It's ready to use!"
+
+❌ **Bad**: "Tool returned: ✅ Organism 'customer_form' created successfully..."
+✅ **Good**: "The form is now live on your ElectroNode. You can start entering customer data!"
+
+---
+
+## Core Concept v2: Event Sourcing
+
+**Create once, mutate incrementally, replay from history.**
+
+- **main.code**: Initial app version (YAML structured: HTML/CSS/JS/activities)
+- **Mutations**: Incremental JavaScript updates (1_add_validation.code, 2_change_color.code, ...)
+- **Snapshots**: Automatic mechanical snapshots every 20 mutations for fast loading
+- **No reloads**: Maintain animations, timers, Three.js scenes, canvas state during mutations
+
+This enables smooth, interactive experiences where the interface evolves based on user actions with complete auditability and rollback capability.
+
+---
+
+## Organism Architecture
+
+### File Structure
+```
+.plasma/organisms/customer_form/      ← BASIC naming (a-zA-Z0-9_, max 4 words)
+├── manifest.yaml                     ← Metadata with frontmatter
+├── main.code                         ← Initial version (YAML structured)
+├── 1_add_validation.code            ← Mutation #1 (JavaScript only)
+├── 2_change_theme.code              ← Mutation #2 (JavaScript only)
+├── ...
+├── 19_fix_layout.code
+├── snapshot_20.code                 ← Automatic snapshot (every 20)
+├── 20_add_button.code
+├── ...
+├── state.json                       ← Optional persistent state
+└── .archive/                        ← Backups (for LLM optimization)
+    └── backup_2026-02-21_14-30/
+```
+
+### manifest.yaml
+```yaml
+---
+name: customer_form
+description: Add and manage customer records
+created: 2026-02-21T10:00:00Z
+updated: 2026-02-21T14:30:00Z
+mutations: 25
+tags: [forms, database, customers]
+---
+```
+
+### main.code (YAML structured)
+```yaml
+---
+activities:
+  - id: btn-submit
+    type: button
+    context: {action: submit_customer}
+  - id: name-input
+    type: input
+    context: {field: name}
+---
+html: |
+  <div class="form">
+    <input id="name-input" placeholder="Name">
+    <input id="email-input" placeholder="Email">
+    <button id="btn-submit">Submit</button>
+    <div id="result"></div>
+  </div>
+
+css: |
+  .form { padding: 20px; max-width: 400px; }
+  button { background: #e91e8c; color: white; padding: 10px 20px; }
+  input { width: 100%; padding: 8px; margin: 4px 0; }
+
+js: |
+  window.app = {
+    resetForm: function() {
+      document.getElementById('name-input').value = '';
+      document.getElementById('email-input').value = '';
+    }
+  };
+```
+
+### Mutation Files (JavaScript only)
+```javascript
+// 1_add_validation.code
+window.app.validate = function() {
+  const name = document.getElementById('name-input').value;
+  if (!name) {
+    alert('Name is required');
+    return false;
+  }
+  return true;
+};
+
+document.getElementById('btn-submit').onclick = function() {
+  if (window.app.validate()) {
+    // Submit logic
+  }
+};
+```
+
+---
+
+## Activities & Feedback Loop
+
+Activities are the bridge between the UI on the node and you (the agent). They let you receive user interactions and respond with feedback on the user's chat (Telegram, WhatsApp, WebChat, etc.).
+
+### How Activities Work
+
+When you define an `activities` array, the node client **auto-injects event listeners** matching element IDs in your HTML. You don't write addEventListener code — just declare the activity and ensure your HTML element has a matching `id`.
+
+### Activity Types
+
+| Type | Auto-Wired Event | What Gets Sent |
+|------|------------------|----------------|
+| `button` | `click` (with preventDefault) | `[Dynamic UI Action] click on #btn-submit context={...} provided={...}` |
+| `input` | `change` | `[Dynamic UI Action] change on #email-input data={value: "user@mail.com"} context={...} provided={...}` |
+| `canvas` | None (manual) | Whatever you send via `window.sendAction()` |
+| `custom` | None (manual) | Whatever you send via `window.sendAction()` |
+
+### The `dataProvider` Field
+
+Use `dataProvider` to attach a **JS expression** to a `button` or `input` activity. The expression is evaluated **at event time** (when the user clicks/changes), and its result is included as `provided` in the action payload.
+
+This replaces the clone-button hack for sending runtime data with auto-wired activities.
+
+```yaml
+activities:
+  - id: btn-submit
+    type: button
+    context: {action: submit_form}
+    dataProvider: "({name: document.getElementById('name').value, email: document.getElementById('email').value})"
+```
+
+When clicked, the agent receives:
+```
+[Dynamic UI Action] click on #btn-submit context={action: "submit_form"} provided={name: "Mario", email: "mario@email.com"}
+```
+
+**Key points**:
+- The expression is wrapped in `eval('(' + expr + ')')` — return an object literal by wrapping in parentheses
+- Errors in `dataProvider` are caught and logged; `provided` will be `undefined` on failure
+- Works on both `button` and `input` activity types
+- `context` is static metadata (set at creation), `provided` is dynamic data (evaluated at event time)
+
+**Examples**:
+
+```yaml
+# Single field value
+dataProvider: "document.getElementById('search').value"
+
+# Multiple fields as object
+dataProvider: "({name: document.getElementById('name').value, qty: parseInt(document.getElementById('qty').value)})"
+
+# App state
+dataProvider: "window.app.getFormData()"
+
+# Computed value
+dataProvider: "document.querySelectorAll('.item.selected').length"
+```
+
+**When to use `dataProvider` vs `custom` type**:
+
+| Scenario | Use |
+|----------|-----|
+| Auto-wired button that also needs form values | `type: button` + `dataProvider` |
+| Complex custom event handling (multiple events, debounce, etc.) | `type: custom` + `window.sendAction()` |
+| Simple "notify agent" button with no runtime data | `type: button` (no dataProvider) |
+
+### The Feedback Loop
+
+This is the key flow — **your response to an action is delivered to the user's chat as text feedback**:
+
+```
+1. User clicks a button on the PLASMA form (on node screen)
+2. Node sends action → gateway → routed to your session
+3. You receive: [Dynamic UI Action] click on #btn-submit data={...} context={action: "submit_form"}
+4. You process the action (validate, save data, call APIs, etc.)
+5. Your text response is sent to the user's chat (Telegram, WhatsApp, etc.)
+6. Optionally, you also update the UI via dynamic_ui_update
+```
+
+**Example**: User fills a form and clicks "Submit" on the PLASMA surface displayed on their Mac:
+- You receive: `[Dynamic UI Action] click on #btn-submit data={} context={action: "submit_customer"}`
+- You read the form data from context or via a follow-up dynamic_ui_update that collects values
+- You respond: "Customer Mario Rossi saved successfully!" → this text appears on Telegram
+- You also call `dynamic_ui_update` to show a green checkmark on the form UI
+
+### Collecting Form Data
+
+For forms, you need the input values. Two approaches:
+
+**A. Use `input` activities** — each field change sends the value automatically:
+```yaml
+activities:
+  - id: name-input
+    type: input
+    context: {field: name}
+  - id: email-input
+    type: input
+    context: {field: email}
+  - id: btn-submit
+    type: button
+    context: {action: submit_form}
+```
+You receive a `change` action for each field as the user types/blurs, then a `click` for submit.
+
+**B. Use `custom` type + `window.sendAction()`** — collect all values at once on submit:
+```javascript
+// In your JS code:
+document.getElementById('btn-submit').addEventListener('click', function(e) {
+  e.preventDefault();
+  window.sendAction('btn-submit', 'submit', {
+    name: document.getElementById('name-input').value,
+    email: document.getElementById('email-input').value,
+    phone: document.getElementById('phone-input').value
+  });
+});
+```
+```yaml
+activities:
+  - id: btn-submit
+    type: custom
+    context: {action: submit_form}
+```
+You receive a single action with all form data in `data={name: "...", email: "...", phone: "..."}`.
+
+**Approach B is recommended for forms** — it's simpler and sends all data at once.
+
+### window.sendAction(activityId, type, data)
+
+For `canvas` and `custom` activity types, a global `window.sendAction()` function is available in the PLASMA surface. Call it from your JS to send any action back to the agent:
+
+```javascript
+// Send a click with form data
+window.sendAction("btn-submit", "submit", {
+  name: document.getElementById("name").value,
+  email: document.getElementById("email").value
+});
+
+// Send a custom drawing event
+window.sendAction("canvas-draw", "draw", { x: 100, y: 200, tool: "pen" });
+
+// Send a selection event
+window.sendAction("item-list", "select", { itemId: 42, label: "Product A" });
+```
+
+### The context Field
+
+Use `context` to pass static metadata that helps you identify what the action means. It is echoed back verbatim in the action message:
+
+```yaml
+activities:
+  - id: btn-approve
+    type: button
+    context: {action: approve, target: invoice, invoiceId: "INV-2026-001"}
+  - id: btn-reject
+    type: button
+    context: {action: reject, target: invoice, invoiceId: "INV-2026-001"}
+```
+
+When clicked, you receive:
+```
+[Dynamic UI Action] click on #btn-approve context={action: "approve", target: "invoice", invoiceId: "INV-2026-001"}
+```
+
+This lets you handle different buttons in the same form without ambiguity.
+
+### Serializing Runtime Data in Actions
+
+**Critical pattern**: Auto-wired `button` activities only send the static `context` — they do NOT include dynamic data from the UI (form values, accumulated records, canvas state, etc.). The data lives in the browser and the agent never sees it unless you explicitly include it.
+
+**The problem** — a button declared as `type: button` without `dataProvider`:
+```yaml
+activities:
+  - id: btn-send
+    type: button
+    context: {action: send_records}
+```
+The agent receives only: `[Dynamic UI Action] click on #btn-send context={action: "send_records"}` — no actual records data.
+
+**Solution A (preferred)** — add `dataProvider` to the activity:
+```yaml
+activities:
+  - id: btn-send
+    type: button
+    context: {action: send_records}
+    dataProvider: "JSON.parse(JSON.stringify(window.app.records))"
+```
+The agent receives: `[Dynamic UI Action] click on #btn-send context={action: "send_records"} provided=[{nome: "Mario", ...}, ...]`
+
+**Solution B** — declare the button as `type: custom` and call `window.sendAction()` with serialized data:
+
+```yaml
+activities:
+  - id: btn-send
+    type: custom
+    context: {action: send_records}
+```
+```javascript
+// In your JS: handle the click yourself and include runtime data
+document.getElementById('btn-send').addEventListener('click', function(e) {
+  e.preventDefault();
+  if (!window.app.records.length) return;
+
+  // Serialize runtime data into the action payload
+  window.sendAction('btn-send', 'click', {
+    context: { action: 'send_records' },
+    records: JSON.parse(JSON.stringify(window.app.records))
+  });
+});
+```
+
+The agent now receives:
+```
+[Dynamic UI Action] click on #btn-send data={context: {action: "send_records"}, records: [{nome: "Mario", cognome: "Rossi", email: "mario@email.com"}, ...]}
+```
+
+#### Retrofitting an existing `type: button` activity
+
+If a button was already declared as `type: button`, the node has auto-wired a click listener on it. To replace it with a custom handler that sends data, clone the element to strip all listeners:
+
+```javascript
+// Remove auto-wired listener via clone trick
+var oldBtn = document.getElementById('btn-send');
+var newBtn = oldBtn.cloneNode(true);
+oldBtn.parentNode.replaceChild(newBtn, oldBtn);
+
+// Attach custom handler with data serialization
+newBtn.addEventListener('click', function(e) {
+  e.preventDefault();
+  window.sendAction('btn-send', 'click', {
+    records: JSON.parse(JSON.stringify(window.app.records))
+  });
+});
+```
+
+This is a valid workaround via `plasma_mutate`, but **prefer declaring `type: custom` from the start** for any button that needs to send runtime data.
+
+#### Which type to use — decision guide
+
+| Scenario | Activity Type | Why |
+|----------|--------------|-----|
+| Button that just notifies the agent ("user clicked X") | `button` | Auto-wired, no JS needed |
+| Button that sends form values or simple computed data | `button` + `dataProvider` | Auto-wired with runtime data, no custom JS |
+| Button with complex event handling (debounce, multi-event, etc.) | `custom` | Full control via `window.sendAction()` |
+| Button that only does client-side work (no agent involvement) | Don't declare as activity | No activity needed — just use normal JS |
+| Input field whose value changes matter to the agent | `input` | Auto-sends value on change |
+| Complex interactive element (canvas, drag-drop, etc.) | `custom` | Full control via `window.sendAction()` |
+
+#### Real-world example — multi-record form
+
+This pattern was used in the Anagrafica organism: a form where the user adds multiple records client-side, then sends them all to the agent at once.
+
+```yaml
+activities:
+  - id: btn-add
+    type: button
+    context: {action: add_record}       # notifies agent a record was added
+  - id: btn-export
+    type: button
+    context: {action: export_csv}       # notifies agent of CSV export
+  - id: btn-send
+    type: custom                        # custom: sends serialized records
+    context: {action: send_records}
+```
+
+```javascript
+// btn-add and btn-export: client-side handlers (no sendAction needed)
+document.getElementById('btn-add').addEventListener('click', function() {
+  window.app.addRecord();  // client-side only
+});
+
+// btn-send: serialize and send all records to the agent
+document.getElementById('btn-send').addEventListener('click', function(e) {
+  e.preventDefault();
+  var records = window.app.records;
+  if (!records.length) { alert('No records'); return; }
+
+  // Visual feedback while sending
+  this.innerHTML = '💎 Invio...';
+  this.style.opacity = '0.7';
+  var btn = this;
+
+  window.sendAction('btn-send', 'click', {
+    context: { action: 'send_records' },
+    records: JSON.parse(JSON.stringify(records))
+  });
+
+  setTimeout(function() {
+    btn.innerHTML = '💎 Inviato ✓';
+    setTimeout(function() { btn.innerHTML = '💎 Invia'; btn.style.opacity = '1'; }, 2000);
+  }, 400);
+});
+```
+
+The agent receives all records and can respond on the user's chat:
+```
+[Dynamic UI Action] click on #btn-send data={context: {action: "send_records"}, records: [{nome: "Mario", cognome: "Rossi", ...}, {nome: "Giulia", cognome: "Bianchi", ...}]}
+```
+
+Agent responds on Telegram: "Received 2 records: Mario Rossi, Giulia Bianchi. Saved to database."
+
+---
+
+## Available Tools
+
+### 1. `plasma_create`
+Create a new organism (app).
+
+**When to use**: User requests a new UI application (form, dashboard, calculator, etc.)
+
+**User says**: "Create a form", "Build a dashboard", "Make a calculator"
+
+**You do**: Call this tool with appropriate HTML/CSS/JS
+
+**Parameters**:
+- `name`: Organism name (a-zA-Z0-9_, max 4 words, descriptive)
+- `description`: What this organism does
+- `html`: HTML content
+- `css`: CSS styles (optional)
+- `js`: JavaScript code (optional)
+- `activities`: Array of interactive elements
+- `tags`: Category tags (optional)
+
+**Naming convention**: Use descriptive names following BASIC rules
+- ✅ Good: `customer_form`, `sales_dashboard`, `task_manager`, `chat_ui`
+- ❌ Bad: `form1`, `my-app`, `SuperCoolApp123`, `very_long_name_with_many_words`
+
+**Example conversation**:
+```
+User: "Create a customer entry form with name and email fields"
+
+You: [Call plasma_create tool internally]
+```
+
+**Tool call** (you make this call, not the user):
+```javascript
+plasma_create({
+  name: "customer_form",
+  description: "Entry form for customer records",
+  html: `
+    <div class="form">
+      <input id="name" placeholder="Name">
+      <input id="email" placeholder="Email">
+      <button id="btn-submit">Submit</button>
+    </div>
+  `,
+  css: `
+    .form { padding: 20px; }
+    button { background: #e91e8c; color: white; }
+  `,
+  js: `
+    window.app = {
+      submitForm: function() { ... }
+    };
+  `,
+  activities: [
+    {id: "btn-submit", type: "button", context: {action: "submit"}}
+  ],
+  tags: ["forms", "database"]
+})
+```
+
+**Tool result** (internal):
+```
+✅ Organism 'customer_form' created successfully
+Saved to: .plasma/organisms/customer_form/
+Files: manifest.yaml, main.code (350 bytes)
+Activities: 1 (#btn-submit)
+```
+
+**You respond to user**:
+"I've created a customer entry form with name and email fields. The form has a submit button that will send you the data when clicked. Would you like me to load it on your ElectroNode now?"
+
+---
+
+### 2. `plasma_mutate`
+Apply an incremental mutation to an existing organism.
+
+**When to use**: User requests changes to an existing app
+
+**User says**:
+- "Add validation to the form"
+- "Change the button color to blue"
+- "Fix the layout"
+- "Add a cancel button"
+
+**You do**: Call this tool with JavaScript that implements the change
+
+**Parameters**:
+- `name`: Organism name
+- `mutation_name`: Descriptive name for mutation (a-zA-Z0-9_)
+- `js`: JavaScript code for the mutation
+- `node_id`: Optional node ID to apply immediately
+
+**Mutation naming**: Be descriptive
+- ✅ Good: `add_validation`, `change_theme_blue`, `fix_button_layout`
+- ❌ Bad: `update`, `fix`, `change`
+
+**Example conversation**:
+```
+User: "Add validation to the customer form - name should be required"
+
+You: [Call plasma_mutate tool internally]
+```
+
+**Tool call** (you make this call):
+```javascript
+plasma_mutate({
+  name: "customer_form",
+  mutation_name: "add_validation",
+  js: `
+    window.app.validate = function() {
+      const name = document.getElementById('name').value;
+      if (!name) {
+        alert('Name required');
+        return false;
+      }
+      return true;
+    };
+
+    document.getElementById('btn-submit').onclick = function() {
+      if (window.app.validate()) {
+        window.app.submitForm();
+      }
+    };
+  `,
+  node_id: "electr-abc123"  // Apply immediately
+})
+```
+
+**Tool result** (internal):
+```
+✅ Mutation applied: 1_add_validation.code
+Total mutations: 1
+Applied to node electr-abc123
+```
+
+**You respond to user**:
+"I've added name validation to the form. It will now show an alert if the user tries to submit without entering a name. The validation is active on your current session and will persist for future loads."
+
+**Automatic snapshots**: Every 20 mutations, a snapshot is created automatically:
+```
+✅ Mutation applied to organism 'customer_form'
+
+Mutation: 20_optimize_render.code
+Total mutations: 20
+
+📸 Snapshot created (snapshot_20.code) for fast loading
+```
+
+---
+
+### 3. `plasma_load`
+Load a saved organism and render it on a node.
+
+**When to use**: User wants to view/open an existing app
+
+**User says**:
+- "Show me the customer form"
+- "Open the sales dashboard"
+- "Launch the calculator"
+- "Load my task manager"
+
+**You do**:
+1. If organism name is ambiguous, call `plasma_list` first
+2. Call `plasma_load` with the organism name and node_id
+
+**Parameters**:
+- `name`: Organism name
+- `node_id`: Target node ID
+
+**Loading strategy** (automatic, transparent):
+1. Find best snapshot (if available) → fast load
+2. Load main.code if no snapshot
+3. Apply remaining mutations in sequence
+4. Render on node
+
+**Example conversation**:
+```
+User: "Show me the customer form"
+
+You: [Call dynamic_ui_list_nodes to get node_id]
+     [Call plasma_load with organism name and node_id]
+```
+
+**Tool call** (you make this call):
+```javascript
+plasma_load({
+  name: "customer_form",
+  node_id: "electr-abc123"
+})
+```
+
+**Tool result** (internal):
+```
+✅ Loaded and rendered on ElectroNode-darwin
+Total mutations: 25
+Loaded from: snapshot_20.code
+Applied 5 additional mutations
+```
+
+**You respond to user**:
+"The customer form is now displayed on your ElectroNode. It includes all 25 updates you've made, including the validation and styling changes. Ready to use!"
+
+**Performance**: With snapshots, loading 100+ mutations takes ~100ms vs ~2s without.
+
+---
+
+### 4. `plasma_list`
+List all saved organisms.
+
+**When to use**: User asks what apps/organisms are available, or when you need to discover organism names
+
+**User says**:
+- "What apps do I have?"
+- "List my organisms"
+- "Show me my UIs"
+
+**You do**: Call this tool (no parameters needed)
+
+**Example conversation**:
+```
+User: "What apps do I have?"
+
+You: [Call plasma_list]
+```
+
+**Tool result** (internal):
+```
+5 PLASMA organism(s) available:
+
+- customer_form (customer_form) — 25 mutations [forms, database]
+  Entry form for customer records
+
+- sales_dashboard (sales_dashboard) — 12 mutations [dashboard, charts]
+  Real-time sales metrics and visualization
+
+- task_manager (task_manager) — 8 mutations [productivity]
+  Simple task list with drag-and-drop
+
+- chat_ui (chat_ui) — 45 mutations [communication]
+  Real-time chat interface with typing indicators
+
+- invoice_gen (invoice_gen) — 3 mutations [pdf, forms]
+  Generate PDF invoices from form data
+```
+
+**You respond to user**:
+"You have 5 Plasma apps:
+1. **Customer Form** (25 updates) - Entry form for customer records
+2. **Sales Dashboard** (12 updates) - Real-time sales metrics
+3. **Task Manager** (8 updates) - Simple task list with drag-and-drop
+4. **Chat UI** (45 updates) - Real-time chat interface
+5. **Invoice Generator** (3 updates) - Generate PDF invoices
+
+Which one would you like to open?"
+
+---
+
+### 5. `plasma_delete`
+Delete an organism permanently.
+
+**When to use**: User wants to remove an app they no longer need
+
+**User says**:
+- "Delete the old form"
+- "Remove the test app"
+- "I don't need the calculator anymore"
+
+**You do**: Call this tool with the organism name
+
+**Important**: Always confirm with the user before deleting unless they explicitly say to delete
+
+**Example conversation**:
+```
+User: "Delete the test form"
+
+You: "Are you sure you want to delete 'test_form'? This will remove it permanently along with all its mutations."
+
+User: "Yes"
+
+You: [Call plasma_delete]
+```
+
+**Tool call** (you make this call):
+```javascript
+plasma_delete({name: "test_form"})
+```
+
+**Tool result** (internal):
+```
+✅ Organism 'test_form' deleted permanently
+```
+
+**You respond to user**:
+"The test form has been deleted permanently. All mutations and history have been removed."
+
+---
+
+### 6. `dynamic_ui_query`
+Execute JavaScript in the DynamicUI surface on a node and return the result.
+
+**When to use**: You need to read runtime state from the UI — form values, accumulated data, DOM state, computed values — without the user triggering an action.
+
+**User says**:
+- "What's in the form right now?"
+- "How many records have been added?"
+- "Read the current settings from the app"
+
+**You do**: Call this tool with a JS expression; the result comes back to you directly.
+
+**Parameters**:
+- `node_id`: Target node ID
+- `js`: JavaScript expression to evaluate (result is returned)
+
+**Example conversation**:
+```
+User: "What data is in the form?"
+
+You: [Call dynamic_ui_query with JS to read form fields]
+```
+
+**Tool call** (you make this call):
+```javascript
+dynamic_ui_query({
+  node_id: "osxnode-abc123",
+  js: "({name: document.getElementById('name').value, email: document.getElementById('email').value})"
+})
+```
+
+**Tool result** (internal):
+```
+Result: {"name": "Mario Rossi", "email": "mario@email.com"}
+```
+
+**You respond to user**:
+"The form currently has: Name = Mario Rossi, Email = mario@email.com"
+
+**More examples**:
+```javascript
+// Read app state
+dynamic_ui_query({ node_id: "...", js: "JSON.stringify(window.app.records)" })
+
+// Count elements
+dynamic_ui_query({ node_id: "...", js: "document.querySelectorAll('.item').length" })
+
+// Check visibility
+dynamic_ui_query({ node_id: "...", js: "document.getElementById('panel').style.display !== 'none'" })
+```
+
+**`dataProvider` vs `dynamic_ui_query`**:
+- `dataProvider`: Evaluated **at event time** (user clicks button) — data travels with the action
+- `dynamic_ui_query`: Evaluated **on demand** (agent calls it) — agent proactively reads UI state
+
+---
+
+## Best Practices
+
+### 0. Use Bootstrap for Forms and Form-Based Applications
+
+**When the user requests a form, a form-based application, or any UI that is primarily form-driven** (contact forms, registration, data entry, surveys, settings panels, etc.), **always use Bootstrap** as the CSS framework.
+
+**Why**: Bootstrap provides consistent, responsive, accessible form layouts out of the box — radio buttons, checkboxes, selects, validation states, input groups, floating labels, and grid alignment all work correctly without custom CSS.
+
+**How**: Load Bootstrap from CDN in the `css` field or via `<link>` in the HTML:
+
+```html
+<!-- In the html field of plasma_create -->
+<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+```
+
+Or load both CSS + JS (for components like modals, tooltips, accordions):
+
+```html
+<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"></script>
+```
+
+**Example form with Bootstrap**:
+```javascript
+plasma_create({
+  name: "customer_form",
+  description: "Customer registration form",
+  html: `
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css" rel="stylesheet">
+    <div class="container py-4" style="max-width: 600px;">
+      <h3 class="mb-4">New Customer</h3>
+      <form id="customer-form">
+        <div class="mb-3">
+          <label for="name" class="form-label">Full Name</label>
+          <input type="text" class="form-control" id="name" required>
+        </div>
+        <div class="mb-3">
+          <label for="email" class="form-label">Email</label>
+          <input type="email" class="form-control" id="email" required>
+        </div>
+        <div class="mb-3">
+          <label for="phone" class="form-label">Phone</label>
+          <input type="tel" class="form-control" id="phone">
+        </div>
+        <button type="submit" id="btn-submit" class="btn btn-primary">Submit</button>
+      </form>
+      <div id="status" class="mt-3"></div>
+    </div>
+  `,
+  activities: [
+    {id: "btn-submit", type: "button", context: {action: "submit_customer"}}
+  ],
+  tags: ["forms", "customers"]
+})
+```
+
+**When NOT to use Bootstrap**: Dashboards, 3D visualizations, games, custom creative UIs, canvas-based apps — use custom CSS or other frameworks as appropriate.
+
+### 1. Always Expose Global State in main.code
+
+**Why**: Mutations need access to app state
+
+```javascript
+// GOOD: In main.code js section
+window.app = {
+  scene: scene,
+  cube: cube,
+  camera: camera,
+  submitForm: function() { ... }
+};
+```
+
+```javascript
+// BAD: Everything local
+const scene = new THREE.Scene();  // Can't access in mutations!
+```
+
+### 2. Descriptive Mutation Names
+
+```javascript
+// GOOD
+plasma_mutate({
+  name: "customer_form",
+  mutation_name: "add_email_validation",
+  js: ...
+})
+
+// BAD
+plasma_mutate({
+  name: "customer_form",
+  mutation_name: "fix",  // Too vague
+  js: ...
+})
+```
+
+### 3. Small, Focused Mutations
+
+```javascript
+// GOOD: One concern per mutation
+1_add_validation.code       → Validation logic
+2_change_button_color.code  → Visual change
+3_add_cancel_button.code    → New feature
+
+// BAD: Giant mutation doing everything
+1_big_update.code  → Changes 10 different things
+```
+
+### 4. Use node_id for Immediate Feedback
+
+```javascript
+// If user is actively using the app, apply mutation immediately
+plasma_mutate({
+  name: "customer_form",
+  mutation_name: "change_theme_dark",
+  js: `
+    document.body.style.background = '#1a1a1a';
+    document.body.style.color = '#ffffff';
+  `,
+  node_id: currentNodeId  // ← Apply now
+})
+```
+
+### 5. Load Libraries from CDN in main.code
+
+```javascript
+// In main.code js section:
+const script = document.createElement('script');
+script.src = 'https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js';
+script.onload = function() {
+  // Three.js loaded, create scene
+  const scene = new THREE.Scene();
+  // ...
+  window.app = { scene, ... };
+};
+document.head.appendChild(script);
+```
+
+---
+
+## Client-Side vs Server-Side Logic
+
+**Golden Rule**: Handle as much as possible client-side. Only involve the server for actions that REQUIRE server capabilities.
+
+### Handle CLIENT-SIDE (via mutations):
+- ✅ Visual changes (color, size, position, rotation)
+- ✅ Animations and transitions
+- ✅ Form validation (basic)
+- ✅ UI state changes (show/hide, enable/disable)
+- ✅ Local filtering/sorting
+- ✅ Canvas drawing
+- ✅ Three.js scene manipulation
+
+**Why**: Instant response, no network latency, preserves state.
+
+### Handle SERVER-SIDE (via activity → agent responds):
+- 📡 Data fetching from external APIs
+- 📡 Database operations
+- 📡 Complex computations
+- 📡 Form submissions requiring persistence
+- 📡 Authentication/authorization
+- 📡 File uploads
+- 📡 IoT device control
+
+**Why**: Requires server capabilities you can't provide in browser.
+
+**Important**: For server-side operations (database, API calls, file processing), use existing MCP tools that the agent already has access to. The agent can invoke any available tool in response to UI actions.
+
+### Example: Color Picker
+
+**USER REQUEST**: "I want to change the cube color"
+
+**CLIENT-SIDE APPROACH** (PREFERRED):
+```javascript
+// Initial render includes color picker activity
+activities: [{id: "color-picker", type: "input", context: {}}]
+
+// User changes color → you receive action
+// [Dynamic UI Action] change on #color-picker data={value: "#ff0000"}
+
+// Response: Direct update (instant)
+dynamic_ui_update({
+  node_id: "...",
+  js: `window.app.cube.material.color.set('${value}');`
+})
+```
+
+**Why this works**: Color change is purely visual, no server needed.
+
+### Example: Weather Data Form
+
+**USER REQUEST**: "Show me a form to get weather for a city"
+
+**HYBRID APPROACH**:
+```javascript
+// 1. Initial render with form (client-side)
+dynamic_ui_render({
+  html: `
+    <input id="city-input" type="text" placeholder="Enter city">
+    <button id="btn-fetch">Get Weather</button>
+    <div id="weather-result"></div>
+  `,
+  activities: [
+    {id: "btn-fetch", type: "button", context: {action: "fetch_weather"}}
+  ]
+})
+
+// 2. User clicks button → you receive:
+// [Dynamic UI Action] click on #btn-fetch
+
+// 3. You fetch weather from server API (server-side)
+const weather = await fetchWeatherAPI(city);
+
+// 4. Update UI with result (client-side)
+dynamic_ui_update({
+  js: `
+    document.getElementById('weather-result').innerHTML = '
+      <h3>${weather.city}</h3>
+      <p>Temperature: ${weather.temp}°C</p>
+      <p>Conditions: ${weather.conditions}</p>
+    ';
+  `
+})
+```
+
+**Why hybrid**: Form display is client-side, but weather API requires server.
+
+---
+
+## When to Use PLASMA vs Dynamic UI Directly
+
+**Use `plasma_create` + `plasma_load` when**:
+- UI will be reused multiple times
+- App should load instantly from disk
+- Want complete change history (event sourcing)
+- Building library of reusable apps
+
+**Use `dynamic_ui_render` directly when**:
+- One-off visualization
+- Highly dynamic content that changes every time
+- Prototyping/testing
+
+**Typical workflow**:
+```javascript
+// 1. Create organism (saved to disk)
+plasma_create({ name: "my_app", ... })
+
+// 2. Evolve it incrementally
+plasma_mutate({ name: "my_app", mutation_name: "add_feature", js: "..." })
+
+// 3. Load it any time
+plasma_load({ name: "my_app", node_id: nodeId })
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Form with Progressive Enhancement
+
+```javascript
+// 1. Create base form
+plasma_create({
+  name: "contact_form",
+  description: "Contact form with progressive enhancements",
+  html: `
+    <div class="form">
+      <input id="name" placeholder="Name">
+      <input id="email" placeholder="Email">
+      <textarea id="message" placeholder="Message"></textarea>
+      <button id="btn-submit">Submit</button>
+      <div id="status"></div>
+    </div>
+  `,
+  activities: [
+    {id: "btn-submit", type: "button", context: {action: "submit"}}
+  ]
+})
+
+// 2. Add validation (mutation #1)
+plasma_mutate({
+  name: "contact_form",
+  mutation_name: "add_validation",
+  js: `
+    window.app.validate = function() {
+      const email = document.getElementById('email').value;
+      if (!email.includes('@')) {
+        document.getElementById('status').textContent = '❌ Invalid email';
+        return false;
+      }
+      return true;
+    };
+  `
+})
+
+// 3. Add character counter (mutation #2)
+plasma_mutate({
+  name: "contact_form",
+  mutation_name: "add_char_counter",
+  js: `
+    const textarea = document.getElementById('message');
+    const counter = document.createElement('div');
+    counter.id = 'counter';
+    textarea.after(counter);
+
+    textarea.oninput = function() {
+      counter.textContent = this.value.length + ' characters';
+    };
+  `
+})
+```
+
+### Pattern 2: Interactive 3D Visualization
+
+```javascript
+// Create Three.js app
+plasma_create({
+  name: "cube_3d",
+  description: "Interactive rotating cube",
+  html: `<div id="container" style="width:100%; height:500px;"></div>`,
+  js: `
+    const script = document.createElement('script');
+    script.src = 'https://cdn.jsdelivr.net/npm/three@0.160.0/build/three.min.js';
+    script.onload = () => {
+      const scene = new THREE.Scene();
+      const camera = new THREE.PerspectiveCamera(75, 800/500, 0.1, 1000);
+      const renderer = new THREE.WebGLRenderer({antialias: true});
+      renderer.setSize(800, 500);
+      container.appendChild(renderer.domElement);
+
+      const cube = new THREE.Mesh(
+        new THREE.BoxGeometry(2,2,2),
+        new THREE.MeshPhongMaterial({color: 0xe91e8c})
+      );
+      scene.add(cube);
+
+      const light = new THREE.DirectionalLight(0xffffff, 1);
+      light.position.set(5,5,5);
+      scene.add(light);
+      camera.position.z = 5;
+
+      function animate() {
+        requestAnimationFrame(animate);
+        cube.rotation.x += 0.01;
+        cube.rotation.y += 0.01;
+        renderer.render(scene, camera);
+      }
+      animate();
+
+      // EXPOSE STATE for mutations
+      window.app = { scene, camera, renderer, cube };
+    };
+    document.head.appendChild(script);
+  `,
+  activities: []
+})
+
+// Mutation: Change color
+plasma_mutate({
+  name: "cube_3d",
+  mutation_name: "change_color_blue",
+  js: `window.app.cube.material.color.set('#0000ff');`,
+  node_id: nodeId
+})
+
+// Mutation: Double size
+plasma_mutate({
+  name: "cube_3d",
+  mutation_name: "double_size",
+  js: `window.app.cube.scale.set(2, 2, 2);`,
+  node_id: nodeId
+})
+```
+
+### Pattern 3: Dashboard with Live Updates
+
+```javascript
+// Create dashboard
+plasma_create({
+  name: "system_monitor",
+  description: "System monitoring dashboard",
+  html: `
+    <div class="dashboard">
+      <h2>System Status</h2>
+      <div id="cpu" class="metric">CPU: --</div>
+      <div id="memory" class="metric">Memory: --</div>
+      <div id="disk" class="metric">Disk: --</div>
+    </div>
+  `,
+  css: `
+    .dashboard { padding: 20px; font-family: monospace; }
+    .metric { font-size: 18px; margin: 10px 0; }
+  `,
+  activities: []
+})
+
+// Server periodically sends updates via mutations
+// (Agent calls plasma_mutate when new data arrives)
+plasma_mutate({
+  name: "system_monitor",
+  mutation_name: "update_metrics",
+  js: `
+    document.getElementById('cpu').textContent = 'CPU: 45%';
+    document.getElementById('memory').textContent = 'Memory: 62%';
+    document.getElementById('disk').textContent = 'Disk: 78%';
+  `,
+  node_id: nodeId
+})
+```
+
+---
+
+## Snapshots (Automatic)
+
+Snapshots are created **automatically every 20 mutations** to optimize loading performance.
+
+### What is a Snapshot?
+
+A snapshot is a **mechanical concatenation** of main.code + all mutations up to N:
+
+```javascript
+// snapshot_20.code (auto-generated)
+// Snapshot at mutation 20
+// Auto-generated: 2026-02-21T14:30:00.000Z
+
+// === main.code ===
+[... full main.code content ...]
+
+// === 1_add_validation.code ===
+[... mutation 1 content ...]
+
+// === 2_change_color.code ===
+[... mutation 2 content ...]
+
+...
+
+// === 20_optimize_render.code ===
+[... mutation 20 content ...]
+```
+
+### Loading Strategy
+
+When loading an organism with 45 mutations:
+
+**Without snapshot** (slow):
+```
+Load: main.code + 1.code + 2.code + ... + 45.code
+= 46 file reads + 45 sequential updates
+```
+
+**With snapshot** (fast):
+```
+Load: snapshot_40.code (includes main + 1-40)
+Apply: 41.code + 42.code + 43.code + 44.code + 45.code
+= 1 snapshot read + 5 mutations
+```
+
+**Result**: ~10x faster loading for mature organisms.
+
+### Snapshot Management
+
+- **Creation**: Automatic at mutations 20, 40, 60, 80, ...
+- **Storage**: Separate .code files (snapshot_N.code)
+- **Selection**: Automatically picks best snapshot when loading
+- **No maintenance needed**: System handles everything
+
+---
+
+## Future: LLM-Based Optimization (plasma_optimize)
+
+**Status**: Planned, not yet implemented
+
+**Concept**: Use LLM to intelligently compact mutations
+
+```javascript
+// Future tool
+plasma_optimize({
+  name: "customer_form",
+  strategy: "smart"  // vs "mechanical"
+})
+```
+
+**What it does**:
+1. Read main.code + all mutations
+2. LLM analyzes and refactors into optimized main.code
+3. Removes dead code (mutation 5 overwrites mutation 2)
+4. Simplifies redundant logic
+5. Validates result in sandbox
+6. Creates backup in .archive/
+7. Replaces main.code if validation passes
+
+**When to use** (future):
+- Organism has >50 mutations
+- Loading is slow even with snapshots
+- Code has accumulated technical debt
+- User requests optimization
+
+**Safety**: Always validates result and creates backup first.
+
+---
+
+## Workflow Examples
+
+### Example 1: Create and Evolve a Form
+
+```
+User: "Create a customer entry form with name and email fields"
+
+You: [Call plasma_create internally with HTML/CSS/JS]
+     "I've created a customer form with name and email input fields and a submit button.
+      Ready to use!"
+
+---
+
+User: "Add validation - email must contain @"
+
+You: [Call plasma_mutate with email validation JS]
+     "Added email validation. The form will now check that the email contains an @ symbol
+      before allowing submission."
+
+---
+
+User: "Make the submit button blue"
+
+You: [Call plasma_mutate with button color change]
+     "Changed the submit button color to blue."
+
+---
+
+User: "Show me the form"
+
+You: [Call dynamic_ui_list_nodes to get node]
+     [Call plasma_load with customer_form]
+     "The customer form is now displayed on your ElectroNode with all updates
+      (validation + blue button). Ready to collect customer data!"
+```
+
+### Example 2: Dashboard with Live Data
+
+```
+User: "Create a sales dashboard showing revenue and orders"
+
+You: [Call plasma_create with dashboard HTML/CSS/JS including Chart.js]
+     "I've created a sales dashboard with revenue and orders metrics.
+      It's ready to display on your node. Want me to load it?"
+
+User: "Yes, and update it with today's data"
+
+You: [Call plasma_load to display]
+     [Fetch sales data from API/database using other tools]
+     [Call plasma_mutate with data update]
+     "Dashboard is live! Showing today's revenue: $15,234 and 42 orders.
+      The chart reflects the hourly breakdown."
+
+---
+
+[Later, when new sales data arrives via webhook/polling]
+
+You: [Call plasma_mutate to update numbers]
+     [Update displayed automatically]
+     "Dashboard updated - revenue now at $18,450 (+$3,216)."
+```
+
+---
+
+## Summary
+
+**PLASMA v2 = Event-Sourced UI with Complete History**
+
+- **Create** organisms with `plasma_create`
+- **Mutate** incrementally with `plasma_mutate`
+- **Load** instantly with `plasma_load` (snapshot support)
+- **Automatic snapshots** every 20 mutations
+- **Complete history** of all changes
+- **Rollback capable** (load specific mutation range)
+- **Zero LLM cost** for snapshots (mechanical)
+- **Future-ready** for LLM optimization
+
+**Three core tools, infinite possibilities, complete auditability.**