ralphflow 0.5.0 → 0.5.2

package/src/dashboard/ui/notifications.js

@@ -0,0 +1,151 @@
+// Notification and decision handling, audio chimes, browser notifications.
+
+import { state, actions } from './state.js';
+import { fetchJson, extractNotifMessage, esc } from './utils.js';
+
+export async function fetchNotifications() {
+  try {
+    const data = await fetchJson('/api/notifications');
+    state.notificationsList = Array.isArray(data) ? data : [];
+    actions.renderSidebar();
+    actions.renderContent();
+  } catch { /* ignore */ }
+}
+
+export async function dismissNotification(id) {
+  try {
+    await fetch(`/api/notification/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    state.notificationsList = state.notificationsList.filter(n => n.id !== id);
+    actions.renderSidebar();
+    actions.renderContent();
+  } catch { /* ignore */ }
+}
+
+export function maybeRequestNotifPermission() {
+  if (state.notifPermissionRequested) return;
+  if (!('Notification' in window)) return;
+  if (Notification.permission === 'default') {
+    state.notifPermissionRequested = true;
+    Notification.requestPermission();
+  }
+}
+
+export function showBrowserNotification(n) {
+  if (!('Notification' in window)) return;
+  if (Notification.permission !== 'granted') return;
+  if (document.hasFocus()) return;
+  const msg = extractNotifMessage(n.payload);
+  new Notification('RalphFlow — ' + (n.loop || 'Notification'), { body: msg });
+}
+
+export async function fetchDecisions() {
+  try {
+    const data = await fetchJson('/api/decisions');
+    state.decisionsList = Array.isArray(data) ? data : [];
+    actions.renderSidebar();
+    actions.renderContent();
+  } catch { /* ignore */ }
+}
+
+export async function dismissDecision(id) {
+  try {
+    await fetch(`/api/decision/${encodeURIComponent(id)}`, { method: 'DELETE' });
+    state.decisionsList = state.decisionsList.filter(d => d.id !== id);
+    actions.renderSidebar();
+    actions.renderContent();
+  } catch { /* ignore */ }
+}
+
+export function showBrowserDecisionNotification(d) {
+  if (!('Notification' in window)) return;
+  if (Notification.permission !== 'granted') return;
+  if (document.hasFocus()) return;
+  new Notification('RalphFlow — Decision: ' + (d.item || d.loop), {
+    body: d.decision + (d.reasoning ? ' — ' + d.reasoning : ''),
+  });
+}
+
+export function renderDecisionGroups(decisions) {
+  // Group by item (STORY-N, TASK-N)
+  const byItem = {};
+  for (const d of decisions) {
+    const key = d.item || 'Other';
+    if (!byItem[key]) byItem[key] = [];
+    byItem[key].push(d);
+  }
+
+  let html = '';
+  for (const [item, itemDecisions] of Object.entries(byItem)) {
+    const groupId = 'dg-' + item.replace(/[^a-zA-Z0-9-]/g, '_');
+    html += `<div class="decision-group">
+      <div class="decision-group-header" data-decision-group="${esc(groupId)}">
+        <span class="group-chevron expanded">&#9654;</span>
+        <span class="group-label">${esc(item)}</span>
+        <span class="group-count">${itemDecisions.length}</span>
+      </div>
+      <div class="decision-group-body" id="${esc(groupId)}">`;
+
+    for (const d of itemDecisions) {
+      const time = new Date(d.timestamp).toLocaleTimeString();
+      html += `<div class="decision-card" data-decision-id="${esc(d.id)}">
+        <div class="decision-card-top">
+          <span class="decision-time">${esc(time)}</span>
+          <span class="decision-agent">${esc(d.agent)}</span>
+          <button class="decision-dismiss" data-dismiss-decision-id="${esc(d.id)}">&times;</button>
+        </div>
+        <div class="decision-summary">${esc(d.decision)}</div>
+        ${d.reasoning ? '<div class="decision-reasoning">' + esc(d.reasoning) + '</div>' : ''}
+      </div>`;
+    }
+    html += '</div></div>';
+  }
+  return html;
+}
+
+export function initAudioContext() {
+  if (state.audioCtxInitialized) return;
+  state.audioCtxInitialized = true;
+  try {
+    state.audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+  } catch (e) {
+    // Silent fail — audio is best-effort
+  }
+}
+
+export function playNotificationChime() {
+  if (!state.audioCtx) return;
+  try {
+    const now = state.audioCtx.currentTime;
+    // First tone: E5 (659 Hz), 120ms
+    const osc1 = state.audioCtx.createOscillator();
+    const gain1 = state.audioCtx.createGain();
+    osc1.type = 'sine';
+    osc1.frequency.value = 659;
+    gain1.gain.setValueAtTime(0.15, now);
+    gain1.gain.exponentialRampToValueAtTime(0.001, now + 0.12);
+    osc1.connect(gain1);
+    gain1.connect(state.audioCtx.destination);
+    osc1.start(now);
+    osc1.stop(now + 0.12);
+    // Second tone: A5 (880 Hz), 150ms, starts 80ms after first
+    const osc2 = state.audioCtx.createOscillator();
+    const gain2 = state.audioCtx.createGain();
+    osc2.type = 'sine';
+    osc2.frequency.value = 880;
+    gain2.gain.setValueAtTime(0, now + 0.08);
+    gain2.gain.linearRampToValueAtTime(0.12, now + 0.1);
+    gain2.gain.exponentialRampToValueAtTime(0.001, now + 0.25);
+    osc2.connect(gain2);
+    gain2.connect(state.audioCtx.destination);
+    osc2.start(now + 0.08);
+    osc2.stop(now + 0.25);
+  } catch (e) {
+    // Silent fail
+  }
+}
+
+export function onFirstInteraction() {
+  initAudioContext();
+  document.removeEventListener('click', onFirstInteraction);
+  document.removeEventListener('keydown', onFirstInteraction);
+}

package/src/dashboard/ui/prompt-builder.js

@@ -0,0 +1,362 @@
+// Prompt configuration form and prompt generation engine.
+// Constants: PROMPT_CAPABILITIES.
+
+import { state, dom, actions } from './state.js';
+
+export const PROMPT_CAPABILITIES = [
+  { id: 'webSearch', label: 'Web search', desc: 'Search the internet for information' },
+  { id: 'mcpServers', label: 'MCP servers', desc: 'Connect to specific MCP tools' },
+  { id: 'exploreAgents', label: 'Explore agents', desc: 'Use Claude Code\'s Agent tool to explore the codebase' },
+  { id: 'fileReadWrite', label: 'File read/write', desc: 'Read or modify specific file types' },
+  { id: 'bashCommands', label: 'Bash commands', desc: 'Run shell commands, build, deploy' },
+  { id: 'codeEditing', label: 'Code editing', desc: 'Modify source code files' }
+];
+
+export function syncStageConfigs(loop) {
+  const existing = loop.stageConfigs || [];
+  loop.stageConfigs = loop.stages.map(stageName => {
+    const found = existing.find(sc => sc.name === stageName);
+    if (found) return found;
+    const caps = {};
+    PROMPT_CAPABILITIES.forEach(c => { caps[c.id] = false; });
+    return { name: stageName, description: '', capabilities: caps };
+  });
+}
+
+export function createEmptyLoop() {
+  return {
+    name: '',
+    stages: [],
+    completion: 'LOOP COMPLETE',
+    model: 'claude-sonnet-4-6',
+    multi_agent: false,
+    max_agents: 3,
+    strategy: 'parallel',
+    agent_placeholder: '{{AGENT_NAME}}',
+    data_files: [],
+    entities: [],
+    showOptional: false,
+    showPrompt: false,
+    prompt: '',
+    inputFiles: '',
+    outputFiles: '',
+    stageConfigs: [],
+    showPromptForm: true,
+    claudeArgs: '',
+    skipPermissions: true,
+    _outputAutoFilled: true,
+    _inputAutoFilled: true
+  };
+}
+
+export function initTemplateBuilderState() {
+  return { name: '', description: '', loops: [createEmptyLoop()] };
+}
+
+// -----------------------------------------------------------------------
+// Prompt config form — structured input for prompt generation
+// -----------------------------------------------------------------------
+
+export function renderPromptConfigForm(loopIdx, loop, allLoops) {
+  let html = '<div class="prompt-config-form" data-config-form-idx="' + loopIdx + '">';
+  html += '<div class="prompt-generate-card">';
+  html += '<div class="prompt-generate-info">Generate a structured prompt from your loop configuration &mdash; stages, input/output files, and model settings will be combined into a ready-to-use agent prompt.</div>';
+  html += `<button class="btn btn-primary generate-prompt-btn" data-generate-prompt="${loopIdx}">Generate Prompt</button>`;
+  html += '</div>';
+  html += '</div>';
+  return html;
+}
+
+// -----------------------------------------------------------------------
+// Visual Communication Protocol for generated prompts
+// -----------------------------------------------------------------------
+
+function generateVisualProtocol() {
+  let s = '';
+  s += `## Visual Communication Protocol\n\n`;
+  s += `When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.\n\n`;
+  s += `**Character set:** \`┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶\`\n\n`;
+  s += `**Diagram types to use:**\n\n`;
+  s += `- **Scope/Architecture Map** — components and their relationships in a bordered grid\n`;
+  s += `- **Decomposition Tree** — hierarchical breakdown with \`├──\` and \`└──\` branches\n`;
+  s += `- **Data Flow** — arrows (\`──→\`) showing how information moves between components\n`;
+  s += `- **Comparison Table** — bordered table for trade-offs and design options\n`;
+  s += `- **Status Summary** — bordered box with completion indicators (\`✓\` done, \`◌\` pending)\n\n`;
+  s += `**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.\n\n`;
+  s += `---\n\n`;
+  return s;
+}
+
+// -----------------------------------------------------------------------
+// Prompt generation engine
+// -----------------------------------------------------------------------
+
+export function generatePromptFromConfig(loop, loopIndex, allLoops) {
+  const loopName = loop.name || 'Loop ' + (loopIndex + 1);
+  const inputFiles = (loop.inputFiles || '').trim();
+  const outputFiles = (loop.outputFiles || '').trim();
+  const completion = loop.completion || 'LOOP COMPLETE';
+
+  // Entity name: use first entity if defined, else "item"
+  const entity = (loop.entities && loop.entities.length > 0) ? loop.entities[0] : '';
+  const entityUpper = entity ? entity.toUpperCase() : 'ITEM';
+  const entityLower = entity ? entity.toLowerCase() : 'item';
+  const entityTitle = entityUpper.charAt(0) + entityLower.slice(1);
+  const entityPlural = entityLower.endsWith('s') ? entityLower : entityLower + 's';
+  const entityKey = entityUpper + '-{N}';
+
+  // Loop directory name: matches createCustomTemplate convention
+  const loopKey = (loopName || 'loop-' + loopIndex)
+    .toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
+  const loopKeyFull = loopKey.endsWith('-loop') ? loopKey : loopKey + '-loop';
+  const dirPrefix = String(loopIndex).padStart(2, '0');
+  const loopDir = dirPrefix + '-' + loopKeyFull;
+
+  // Pipeline display
+  const pipelineIn = inputFiles || 'input.md';
+  const pipelineOut = outputFiles || 'output.md';
+
+  // Primary input file for read-only references
+  const primaryInputFile = inputFiles ? inputFiles.split(',')[0].trim() : '';
+
+  let p = '';
+
+  // ── HEADER / IDENTITY ──
+  p += `# ${loopName} Loop\n\n`;
+  p += `**App:** \`{{APP_NAME}}\` — all flow files live under \`.ralph-flow/{{APP_NAME}}/\`.\n\n`;
+  if (loop.multi_agent) {
+    p += `**You are agent \`{{AGENT_NAME}}\`.** Multiple agents may work in parallel.\n`;
+    p += `Coordinate via \`tracker.md\` — the single source of truth.\n`;
+    p += `*(If you see the literal text \`{{AGENT_NAME}}\` above — i.e., it was not substituted — treat your name as \`agent-1\`.)*\n\n`;
+  }
+  p += `Read \`.ralph-flow/{{APP_NAME}}/${loopDir}/tracker.md\` FIRST to determine where you are.\n\n`;
+  p += `> **PROJECT CONTEXT.** Read \`CLAUDE.md\` for architecture, stack, conventions, commands, and URLs.\n\n`;
+  p += `**Pipeline:** \`${pipelineIn} → YOU → ${pipelineOut}\`\n\n`;
+  p += `---\n\n`;
+
+  // ── VISUAL COMMUNICATION PROTOCOL ──
+  p += generateVisualProtocol();
+
+  // ── MULTI-AGENT SECTIONS (conditional) ──
+  if (loop.multi_agent) {
+    // Tracker Lock Protocol
+    p += `## Tracker Lock Protocol\n\n`;
+    p += `Before ANY write to \`tracker.md\`, you MUST acquire the lock:\n\n`;
+    p += `**Lock file:** \`.ralph-flow/{{APP_NAME}}/${loopDir}/.tracker-lock\`\n\n`;
+    p += `### Acquire Lock\n`;
+    p += `1. Check if \`.tracker-lock\` exists\n`;
+    p += `   - Exists AND file is < 60 seconds old → sleep 2s, retry (up to 5 retries)\n`;
+    p += `   - Exists AND file is ≥ 60 seconds old → stale lock, delete it (agent crashed mid-write)\n`;
+    p += `   - Does not exist → continue\n`;
+    p += `2. Write lock: \`echo "{{AGENT_NAME}} $(date -u +%Y-%m-%dT%H:%M:%SZ)" > .ralph-flow/{{APP_NAME}}/${loopDir}/.tracker-lock\`\n`;
+    p += `3. Sleep 500ms (\`sleep 0.5\`)\n`;
+    p += `4. Re-read \`.tracker-lock\` — verify YOUR agent name (\`{{AGENT_NAME}}\`) is in it\n`;
+    p += `   - Your name → you own the lock, proceed to write \`tracker.md\`\n`;
+    p += `   - Other name → you lost the race, retry from step 1\n`;
+    p += `5. Write your changes to \`tracker.md\`\n`;
+    p += `6. Delete \`.tracker-lock\` immediately: \`rm .ralph-flow/{{APP_NAME}}/${loopDir}/.tracker-lock\`\n`;
+    p += `7. Never leave a lock held — if your write fails, delete the lock in your error handler\n\n`;
+    p += `### When to Lock\n`;
+    p += `- Claiming a ${entityLower} (pending → in_progress)\n`;
+    p += `- Completing a ${entityLower} (in_progress → completed, unblocking dependents)\n`;
+    p += `- Updating stage transitions\n`;
+    p += `- Heartbeat updates (bundled with other writes, not standalone)\n\n`;
+    p += `### When NOT to Lock\n`;
+    p += `- Reading \`tracker.md\` — read-only access needs no lock\n`;
+    if (primaryInputFile) {
+      p += `- Reading \`${primaryInputFile}\` — always read-only\n`;
+    }
+    p += `\n---\n\n`;
+
+    // Item Selection Algorithm
+    p += `## ${entityTitle} Selection Algorithm\n\n`;
+    p += `1. **Parse tracker** — read \`completed_${entityPlural}\`, \`## Dependencies\`, ${entityTitle}s Queue metadata \`{agent, status}\`, Agent Status table\n`;
+    p += `2. **Update blocked→pending** — for each ${entityLower} with \`status: blocked\`, check if ALL its dependencies (from \`## Dependencies\`) are in \`completed_${entityPlural}\`. If yes, acquire lock and update to \`status: pending\`\n`;
+    p += `3. **Resume own work** — if any ${entityLower} has \`{agent: {{AGENT_NAME}}, status: in_progress}\`, resume it (skip to the current stage)\n`;
+    p += `4. **Find claimable** — filter ${entityPlural} where \`status: pending\` AND \`agent: -\`\n`;
+    p += `5. **Claim** — acquire lock, set \`{agent: {{AGENT_NAME}}, status: in_progress}\`, update your Agent Status row, update \`last_heartbeat\`, release lock, log the claim\n`;
+    p += `6. **Nothing available:**\n`;
+    p += `   - All ${entityPlural} completed → emit \`<promise>${completion}</promise>\`\n`;
+    p += `   - All remaining ${entityPlural} are blocked or claimed by others → log "{{AGENT_NAME}}: waiting — all ${entityPlural} blocked or claimed", exit: \`kill -INT $PPID\`\n\n`;
+    p += `### New ${entityTitle} Discovery\n\n`;
+    p += `If you find a ${entityLower} in the Queue without \`{agent, status}\` metadata:\n`;
+    p += `1. Read its \`**Depends on:**\` field\n`;
+    p += `2. Add the dependency to \`## Dependencies\` section if not already there (skip if \`Depends on: None\`)\n`;
+    p += `3. Set status to \`pending\` (all deps in \`completed_${entityPlural}\`) or \`blocked\` (deps incomplete)\n`;
+    p += `4. Set agent to \`-\`\n\n`;
+    p += `---\n\n`;
+
+    // Anti-Hijacking Rules
+    p += `## Anti-Hijacking Rules\n\n`;
+    p += `1. **Never touch another agent's \`in_progress\` ${entityLower}** — do not modify, complete, or reassign it\n`;
+    p += `2. **Respect ownership** — if another agent is active in a group, leave remaining group ${entityPlural} for them\n`;
+    p += `3. **Note file overlap conflicts** — if your ${entityLower} modifies files that another agent's active ${entityLower} also modifies, log a WARNING in the tracker\n\n`;
+    p += `---\n\n`;
+
+    // Heartbeat Protocol
+    p += `## Heartbeat Protocol\n\n`;
+    p += `Every tracker write includes updating your \`last_heartbeat\` to current ISO 8601 timestamp in the Agent Status table. If another agent's heartbeat is **30+ minutes stale**, log a WARNING in the tracker log but do NOT auto-reclaim their ${entityLower} — user must manually reset.\n\n`;
+    p += `---\n\n`;
+
+    // Crash Recovery
+    p += `## Crash Recovery (Self)\n\n`;
+    p += `On fresh start, if your agent name has an \`in_progress\` ${entityLower} but you have no memory of it:\n`;
+    const lastStage = loop.stages.length > 1 ? loop.stages[loop.stages.length - 1] : 'last';
+    const firstStage = loop.stages[0] || 'first';
+    p += `- Work committed for that ${entityLower} → resume at ${lastStage.toUpperCase()} stage\n`;
+    p += `- No work found → restart from ${firstStage.toUpperCase()} stage\n\n`;
+    p += `---\n\n`;
+  }
+
+  // ── STATE MACHINE ──
+  const stageCount = loop.stages.length;
+  p += `## State Machine (${stageCount} stage${stageCount !== 1 ? 's' : ''} per ${entityLower})\n\n\`\`\`\n`;
+  loop.stages.forEach((stage, i) => {
+    const sc = loop.stageConfigs[i];
+    const desc = (sc && sc.description) ? sc.description.split('\n')[0].substring(0, 55) : 'Complete this stage';
+    const next = i < stageCount - 1 ? `→ stage: ${loop.stages[i + 1]}` : `→ next ${entityLower}`;
+    p += `${stage.toUpperCase()}  → ${desc}  ${next}\n`;
+  });
+  p += `\`\`\`\n\n`;
+  p += `When ALL done: \`<promise>${completion}</promise>\`\n\n`;
+  p += `After completing ANY stage, exit: \`kill -INT $PPID\`\n\n`;
+  p += `---\n\n`;
+
+  // ── FIRST-RUN / NEW ITEM DETECTION ──
+  {
+    const scanFile = primaryInputFile || 'input.md';
+    p += `## First-Run / New ${entityTitle} Detection\n\n`;
+    if (loop.multi_agent) {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` with \`{agent: -, status: pending|blocked}\` metadata (compute from Dependencies), then start.\n\n`;
+    } else {
+      p += `If ${entityTitle}s Queue in tracker is empty OR all entries are \`[x]\`: read \`${scanFile}\`, scan \`## ${entityKey}:\` headers + \`**Depends on:**\` tags. For any ${entityLower} NOT already in the queue, add as \`- [ ] ${entityKey}: {title}\` and update Dependencies. If new ${entityPlural} were added, proceed to process them.\n\n`;
+    }
+    p += `---\n\n`;
+  }
+
+  // ── STAGE INSTRUCTIONS ──
+  loop.stages.forEach((stage, i) => {
+    const sc = loop.stageConfigs[i];
+    p += `## STAGE ${i + 1}: ${stage.toUpperCase()}\n\n`;
+
+    if (sc && sc.description) {
+      p += `${sc.description}\n\n`;
+    }
+
+    let step = 1;
+
+    // First stage in multi-agent: run selection algorithm
+    if (loop.multi_agent && i === 0) {
+      p += `${step++}. Read tracker → **run ${entityLower} selection algorithm** (see above)\n`;
+    } else {
+      p += `${step++}. Read tracker → determine current state\n`;
+    }
+
+    // Capability-driven steps
+    if (sc && sc.capabilities) {
+      if (sc.capabilities.fileReadWrite) {
+        const files = primaryInputFile ? ` (\`${primaryInputFile}\`)` : '';
+        p += `${step++}. Read relevant input files${files} and explore affected areas\n`;
+      }
+      if (sc.capabilities.exploreAgents) {
+        p += `${step++}. Use the Agent tool to explore the codebase — read **40+ files** across affected areas, dependencies, patterns\n`;
+      }
+      if (sc.capabilities.webSearch) {
+        p += `${step++}. Use WebSearch for 5-10 queries to gather external information\n`;
+      }
+      if (sc.capabilities.mcpServers) {
+        p += `${step++}. Use MCP tools for specialized operations\n`;
+      }
+      if (sc.capabilities.codeEditing) {
+        p += `${step++}. Implement changes, matching existing patterns per \`CLAUDE.md\`\n`;
+      }
+      if (sc.capabilities.bashCommands) {
+        p += `${step++}. Run build/deploy commands to verify changes\n`;
+      }
+    }
+
+    // Visual diagram trigger
+    if (i === 0) {
+      p += `${step++}. **Render a Scope Diagram** — output an ASCII architecture/scope map showing the areas this ${entityLower} touches, dependencies, and what needs to change\n`;
+    }
+    if (i === stageCount - 1 && stageCount > 1) {
+      p += `${step++}. **Render a Completion Summary** — output an ASCII status diagram showing what was built/changed, verification results, and how this ${entityLower} fits in overall progress\n`;
+    }
+
+    // Tracker update
+    if (loop.multi_agent) {
+      p += `${step++}. Acquire lock → update tracker: stage, \`last_heartbeat\`, log entry → release lock\n`;
+    } else {
+      p += `${step++}. Update tracker with progress\n`;
+    }
+    p += `${step++}. Exit: \`kill -INT $PPID\`\n\n`;
+
+    if (i < stageCount - 1) p += `---\n\n`;
+  });
+
+  // ── OUTPUT FORMAT (when output files and entities are configured) ──
+  if (outputFiles && entity) {
+    p += `---\n\n`;
+    p += `## Output Format\n\n`;
+    p += `Write to \`${outputFiles.split(',')[0].trim()}\` using this format:\n\n`;
+    p += `\`\`\`markdown\n`;
+    p += `## ${entityKey}: {Title}\n\n`;
+    p += `**Depends on:** {dependency or "None"}\n\n`;
+    p += `### Description\n`;
+    p += `{Content for this ${entityLower}}\n\n`;
+    p += `### Acceptance Criteria\n`;
+    p += `- [ ] {Criterion 1}\n`;
+    p += `- [ ] {Criterion 2}\n`;
+    p += `\`\`\`\n\n`;
+  }
+
+  // ── RULES ──
+  p += `---\n\n## Rules\n\n`;
+  p += `- One ${entityLower} at a time${loop.multi_agent ? ' per agent' : ''}. One stage per iteration.\n`;
+  p += `- Read tracker first, update tracker last.${loop.multi_agent ? ' Always use lock protocol for writes.' : ''}\n`;
+  p += `- Read \`CLAUDE.md\` for all project-specific context.\n`;
+  p += `- Thorough exploration before making changes.\n`;
+  if (loop.multi_agent) {
+    p += `- **Multi-agent: never touch another agent's in_progress ${entityLower}. Coordinate via tracker.md.**\n`;
+  }
+
+  // ── CLOSING ──
+  p += `\n---\n\n`;
+  p += `Read \`.ralph-flow/{{APP_NAME}}/${loopDir}/tracker.md\` now and begin.\n`;
+
+  return p;
+}
+
+// -----------------------------------------------------------------------
+// Event bindings for prompt config form
+// -----------------------------------------------------------------------
+
+export function bindPromptConfigFormEvents() {
+  // "Generate Prompt" button
+  dom.content.querySelectorAll('[data-generate-prompt]').forEach(btn => {
+    btn.addEventListener('click', () => {
+      capturePromptConfigFormInputs();
+      const idx = parseInt(btn.dataset.generatePrompt);
+      const loop = state.templateBuilderState.loops[idx];
+      loop.prompt = generatePromptFromConfig(loop, idx, state.templateBuilderState.loops);
+      loop.showPromptForm = false;
+      actions.renderTemplateBuilder();
+    });
+  });
+
+  // "Generate New" button (switch back to form)
+  dom.content.querySelectorAll('[data-show-prompt-form]').forEach(btn => {
+    btn.addEventListener('click', () => {
+      actions.captureBuilderInputs();
+      const idx = parseInt(btn.dataset.showPromptForm);
+      const loop = state.templateBuilderState.loops[idx];
+      loop.showPromptForm = true;
+      loop.prompt = '';
+      actions.renderTemplateBuilder();
+    });
+  });
+}
+
+export function capturePromptConfigFormInputs() {
+  // No-op — form inputs are now captured via the loop card's captureBuilderInputs
+}

package/src/dashboard/ui/sidebar.js

@@ -0,0 +1,97 @@
+// Sidebar rendering, app/loop selection, navigation.
+
+import { state, dom, actions } from './state.js';
+import { calculatePipelineProgress, esc } from './utils.js';
+
+export function renderSidebar() {
+  let html = '';
+  for (const app of state.apps) {
+    const appActive = state.selectedApp && state.selectedApp.appName === app.appName;
+    const appProgress = calculatePipelineProgress(app.loops);
+    html += `<div class="sidebar-item app-item${appActive ? ' active' : ''}" data-app="${esc(app.appName)}">
+      ${esc(app.appName)}
+      <span class="badge">${esc(app.appType)}</span>
+    </div>`;
+    html += `<div class="sidebar-progress">
+      <div class="sidebar-progress-bar"><div class="sidebar-progress-fill" style="width:${appProgress.percentage}%"></div></div>
+      <span class="sidebar-progress-text">${appProgress.percentage}%</span>
+    </div>`;
+    if (app.loops) {
+      for (const loop of app.loops) {
+        const loopActive = appActive && state.selectedLoop === loop.key;
+        const loopNotifCount = state.notificationsList.filter(n => n.app === app.appName && n.loop === loop.key).length;
+        const loopDecisionCount = state.decisionsList.filter(d => d.app === app.appName && d.loop === loop.key).length;
+        const notifBadge = loopNotifCount > 0 ? ` <span class="notif-badge">${loopNotifCount}</span>` : '';
+        const decisionBadge = loopDecisionCount > 0 ? ` <span class="decision-badge">${loopDecisionCount}</span>` : '';
+        html += `<div class="sidebar-item loop-item${loopActive ? ' active' : ''}" data-app="${esc(app.appName)}" data-loop="${esc(loop.key)}">
+          ${esc(loop.name)}${notifBadge}${decisionBadge}
+        </div>`;
+      }
+    }
+  }
+  dom.sidebarApps.innerHTML = html;
+
+  // "+ New App" button
+  const newAppBtn = document.createElement('button');
+  newAppBtn.className = 'new-app-btn';
+  newAppBtn.innerHTML = '+ New App';
+  newAppBtn.addEventListener('click', () => actions.openCreateAppModal());
+  dom.sidebarApps.appendChild(newAppBtn);
+
+  // Event delegation
+  dom.sidebarApps.querySelectorAll('.app-item').forEach(el => {
+    el.addEventListener('click', () => {
+      const app = state.apps.find(a => a.appName === el.dataset.app);
+      if (app) selectApp(app);
+    });
+  });
+  dom.sidebarApps.querySelectorAll('.loop-item').forEach(el => {
+    el.addEventListener('click', () => {
+      const app = state.apps.find(a => a.appName === el.dataset.app);
+      if (app) {
+        selectApp(app);
+        selectLoop(el.dataset.loop);
+      }
+    });
+  });
+
+  // Update Templates nav active state
+  const templatesNav = document.getElementById('templatesNav');
+  if (templatesNav) {
+    templatesNav.classList.toggle('active', state.currentPage === 'templates');
+  }
+}
+
+export function selectApp(app) {
+  state.currentPage = 'app';
+  state.selectedApp = app;
+  state.selectedLoop = app.loops.length > 0 ? app.loops[0].key : null;
+  state.promptDirty = false;
+  state.promptOriginal = '';
+  state.promptViewMode = 'read';
+  state.activeEditTab = 'prompt';
+  state.cachedPromptValue = null;
+  state.activeAppTab = 'loops';
+  state.archivesData = [];
+  state.expandedArchive = null;
+  state.archiveFilesCache = {};
+  state.viewingArchiveFile = null;
+  state.viewingTemplateName = null;
+  state.viewingTemplateConfig = null;
+  state.viewingTemplatePrompts = {};
+  document.title = app.appName + ' - RalphFlow Dashboard';
+  renderSidebar();
+  actions.renderContent();
+  actions.fetchAppStatus(app.appName);
+}
+
+export function selectLoop(loopKey) {
+  state.selectedLoop = loopKey;
+  state.promptDirty = false;
+  state.promptOriginal = '';
+  state.promptViewMode = 'read';
+  state.activeEditTab = 'prompt';
+  state.cachedPromptValue = null;
+  renderSidebar();
+  actions.renderContent();
+}

package/src/dashboard/ui/state.js

@@ -0,0 +1,54 @@
+// Dashboard global state and DOM references
+// All mutable state lives here so modules can share it via import.
+
+export const $ = (sel) => document.querySelector(sel);
+
+export const dom = {
+  hostDisplay: $('#hostDisplay'),
+  sidebarApps: $('#sidebarApps'),
+  content: $('#content'),
+  statusDot: $('#statusDot'),
+  statusText: $('#statusText'),
+  lastUpdate: $('#lastUpdate'),
+  eventCountEl: $('#eventCount'),
+};
+
+export const state = {
+  apps: [],
+  selectedApp: null,
+  selectedLoop: null,
+  eventCounter: 0,
+  promptDirty: false,
+  promptOriginal: '',
+  ws: null,
+  reconnectDelay: 1000,
+  activeEditTab: 'prompt',
+  promptViewMode: 'read',
+  cachedPromptValue: null,
+  notificationsList: [],
+  decisionsList: [],
+  notifPermissionRequested: false,
+  audioCtx: null,
+  audioCtxInitialized: false,
+  activeAppTab: 'loops',
+  archivesData: [],
+  expandedArchive: null,
+  archiveFilesCache: {},
+  viewingArchiveFile: null,
+  currentPage: 'app',
+  templatesList: [],
+  showTemplateBuilder: false,
+  templateBuilderState: null,
+  editingTemplateName: null,
+  selectedBuilderLoop: 0,
+  viewingTemplateName: null,
+  viewingTemplateConfig: null,
+  viewingTemplatePrompts: {},
+  showTemplateWizard: false,
+  wizardStep: 0,
+  wizardData: null,
+};
+
+// Cross-module function registry.
+// Modules register callable functions here to avoid circular imports.
+export const actions = {};