fraim 2.0.159 → 2.0.160

package/public/ai-hub/script.js

@@ -24,6 +24,13 @@ const state = {
   modalPersonaFilter: null,  // R3+: filter inside new-job modal; null = "All jobs"
   storedApiKey: null,        // R2: loaded from preferences, sent on bootstrap
   panelState: {},            // { [convId]: { coach?: boolean } }
+  wordContext: null,         // WordContext pushed from taskpane.html via postMessage
+  // Pending coaching job selected via a quick-coach button or template picker.
+  // Sent as coachingJobId in the next continueRun call and then cleared.
+  // The invocation prefix ($fraim / /fraim) is added server-side based on
+  // the active employee; the user never sees the raw invocation syntax.
+  pendingCoachingJobId: null,
+  pendingCoachingLabel: null,
 };
 
 const els = {};
@@ -60,6 +67,9 @@ function gatherElements() {
     // Issue #442: A/B mode elements.
     'ab-toggle-wrap', 'ab-direct-panel',
     'ab-direct-totals', 'ab-direct-progress', 'ab-direct-send',
+    // Issue #489: Word context elements.
+    'word-context-bar', 'word-ctx-text', 'word-ctx-refresh',
+    'word-context-card', 'word-ctx-card-label', 'word-ctx-card-body', 'word-ctx-card-toggle',
   ];
   for (const id of ids) {
     els[id] = document.getElementById(id);
@@ -67,6 +77,14 @@ function gatherElements() {
 }
 
 async function requestJson(url, options) {
+  // On localhost inject x-api-key: local-dev so the dev server auth bypass fires.
+  // The server's isLocalDev check already gates this to NODE_ENV !== 'production',
+  // so this header is harmless if accidentally sent to a non-dev server.
+  const isLocalHost = window.location.hostname === 'localhost' || window.location.hostname === '127.0.0.1';
+  if (isLocalHost) {
+    const headers = { 'x-api-key': 'local-dev', ...((options && options.headers) || {}) };
+    options = { ...(options || {}), headers };
+  }
   const response = await fetch(url, options);
   let payload = null;
   try { payload = await response.json(); } catch { /* may be empty */ }
@@ -78,10 +96,13 @@ async function requestJson(url, options) {
   return payload;
 }
 
-async function loadBootstrap(projectPath) {
-  const query = projectPath ? `?projectPath=${encodeURIComponent(projectPath)}` : '';
+async function loadBootstrap(projectPath, docUrl) {
+  const params = new URLSearchParams();
+  if (projectPath) params.set('projectPath', projectPath);
+  if (docUrl) params.set('docUrl', docUrl);
+  const query = params.toString() ? '?' + params.toString() : '';
   const fetchOptions = {};
-  if (state.storedApiKey) fetchOptions.headers = { 'x-fraim-api-key': state.storedApiKey };
+  if (state.storedApiKey) fetchOptions.headers = { 'x-api-key': state.storedApiKey };
   const bootstrap = await requestJson(`/api/ai-hub/bootstrap${query}`, fetchOptions);
   state.bootstrap = bootstrap;
   state.projectPath = bootstrap.project.path;
@@ -94,6 +115,20 @@ async function loadBootstrap(projectPath) {
   els['project-name'].textContent = friendlyProjectName(bootstrap.project.path);
   els['status-line'].textContent = bootstrap.project.message || '';
   els['status-line'].classList.toggle('error', !bootstrap.project.exists || !bootstrap.project.hasFraim);
+  // Update the compact project label shown in task-pane surface rail.
+  const tpLabel = document.getElementById('tp-project-label');
+  if (tpLabel) {
+    const projectName = friendlyProjectName(bootstrap.project.path);
+    const resolvedDocUrl = docUrl || new URLSearchParams(window.location.search).get('docUrl') || '';
+    let docName = '';
+    if (resolvedDocUrl) {
+      try {
+        const rawName = resolvedDocUrl.replace(/\\/g, '/').split('/').pop() || '';
+        docName = decodeURIComponent(rawName).replace(/\.[^.]+$/, '');
+      } catch {}
+    }
+    tpLabel.textContent = docName ? `${projectName}  ·  ${docName}` : projectName;
+  }
   // Populate the welcome-line popovers with REAL jobs from the bootstrap.
   populateConceptPopovers();
   // Render rail and active state for this project.
@@ -101,6 +136,121 @@ async function loadBootstrap(projectPath) {
   renderActive();
 }
 
+// ---------------------------------------------------------------------------
+// Word context bridge (postMessage from taskpane.html parent frame)
+// ---------------------------------------------------------------------------
+
+// Apply a full or partial Word context update and re-render dependent UI.
+// Called by the postMessage bridge and usable directly in tests.
+function applyWordContext(ctx, partial) {
+  if (partial) {
+    if (!state.wordContext) state.wordContext = {};
+    Object.assign(state.wordContext, ctx || {});
+  } else {
+    state.wordContext = ctx || null;
+  }
+  renderWordContextBar();
+  renderWordContextInModal();
+}
+
+function setupWordBridge() {
+  if (window.parent === window) return; // not inside an iframe — no bridge needed
+  window.addEventListener('message', function(event) {
+    if (event.source !== window.parent) return;
+    const msg = event.data || {};
+    if (msg.type === 'word-context') {
+      applyWordContext(msg.payload, false);
+    } else if (msg.type === 'word-context-update') {
+      applyWordContext(msg.payload, true);
+    }
+    // word-response messages are handled by per-request listeners in requestWordContext()
+  });
+  // Signal taskpane.html that Hub is ready to receive context.
+  window.parent.postMessage({ type: 'hub-ready' }, '*');
+}
+
+// Send a word-request to taskpane.html and await the word-response.
+// Resolves null if not in iframe, no response, or timeout (3 s).
+function requestWordContext(action, payload) {
+  return new Promise(function(resolve) {
+    if (window.parent === window) { resolve(null); return; }
+    const requestId = Math.random().toString(36).slice(2);
+    const timer = setTimeout(function() { cleanup(); resolve(null); }, 3000);
+    function onMsg(event) {
+      if (event.source !== window.parent) return;
+      const m = event.data || {};
+      if (m.type === 'word-response' && m.requestId === requestId) {
+        cleanup(); resolve(m.payload || null);
+      }
+    }
+    function cleanup() { clearTimeout(timer); window.removeEventListener('message', onMsg); }
+    window.addEventListener('message', onMsg);
+    window.parent.postMessage({ type: 'word-request', requestId, action, payload: payload || {} }, '*');
+  });
+}
+
+function buildWordContextBlock(wc) {
+  if (!wc) return '';
+  const parts = [];
+  if (wc.docTitle) parts.push(`Document: ${wc.docTitle}`);
+  if (wc.selection) {
+    const wordCount = wc.selection.split(/\s+/).filter(Boolean).length;
+    parts.push(`Selected text (${wordCount} word${wordCount !== 1 ? 's' : ''}):\n"""\n${wc.selection.slice(0, 500)}\n"""`);
+  } else if (wc.bodyPreview) {
+    parts.push(`Document preview:\n"""\n${wc.bodyPreview.slice(0, 800)}\n"""`);
+  }
+  if (wc.wordCount) parts.push(`Document length: ~${wc.wordCount} words`);
+  if (wc.comments && wc.comments.length > 0) {
+    const lines = wc.comments.slice(0, 5).map(c => `- ${c.author || 'Author'}: ${c.text}`).join('\n');
+    parts.push(`Document comments (${wc.comments.length}):\n${lines}`);
+  }
+  if (parts.length === 0) return '';
+  return `[Word Document Context]\n${parts.join('\n\n')}`;
+}
+
+function renderWordContextBar() {
+  const bar = els['word-context-bar'];
+  const txt = els['word-ctx-text'];
+  if (!bar || !txt) return;
+  const wc = state.wordContext;
+  if (!wc || (!wc.docTitle && !wc.selection && !wc.bodyPreview)) {
+    bar.hidden = true;
+    return;
+  }
+  bar.hidden = false;
+  if (wc.selection) {
+    const words = wc.selection.split(/\s+/).filter(Boolean).length;
+    txt.textContent = `${words} word${words !== 1 ? 's' : ''} selected — "${wc.selection.slice(0, 60)}${wc.selection.length > 60 ? '…' : ''}"`;
+  } else if (wc.bodyPreview) {
+    const words = wc.wordCount || 0;
+    txt.textContent = `${wc.docTitle || 'Document'} · ${words} words — full doc context active`;
+  } else {
+    txt.textContent = wc.docTitle || 'Document context active';
+  }
+}
+
+function renderWordContextInModal() {
+  const card = els['word-context-card'];
+  const label = els['word-ctx-card-label'];
+  const body = els['word-ctx-card-body'];
+  if (!card || !label || !body) return;
+  const wc = state.wordContext;
+  if (!wc || (!wc.selection && !wc.bodyPreview && !wc.comments?.length)) {
+    card.hidden = true;
+    return;
+  }
+  card.hidden = false;
+  // Label line: "3 words selected · MyDoc" or "MyDoc · 1,234 words"
+  if (wc.selection) {
+    const words = wc.selection.split(/\s+/).filter(Boolean).length;
+    label.textContent = `${words} word${words !== 1 ? 's' : ''} selected${wc.docTitle ? ' · ' + wc.docTitle : ''}`;
+  } else {
+    label.textContent = (wc.docTitle || 'Document') + (wc.wordCount ? ` · ${wc.wordCount} words` : '');
+  }
+  // Body: shows block that will be sent to the agent
+  body.textContent = buildWordContextBlock(wc);
+}
+
 // ---------------------------------------------------------------------------
 // Concept popover population (drives the welcome-line "see ... jobs" lists)
 // ---------------------------------------------------------------------------
@@ -714,6 +864,9 @@ function renderActive() {
     renderedMessageCount = 0;
     renderedEventCount = 0;
     renderedDirectEventCount = 0;
+    // A pending coaching job is scoped to the active conversation — discard it
+    // whenever the user switches to a different conversation.
+    clearPendingCoachingJob();
   }
   const statusChanged = renderedStatus !== conv.status;
   syncConversationPanels(conv, switchedConv);
@@ -1238,26 +1391,21 @@ function closeTemplatePopover() {
 }
 
 function applyTemplateInvocation(managerJobId) {
-  const conv = activeConversation();
-  // Use the conversation's own employee for the invocation symbol, NOT
-  // the manager's last selection in another conversation (R2.5).
-  const employeeId = (conv && conv.employeeId) || state.selectedEmployeeId || 'claude';
-  const symbol = FRAIM_INVOCATION_SYMBOL[employeeId] || '/fraim';
-  const invocation = `${symbol} ${managerJobId}`;
+  // The invocation prefix ($fraim / /fraim) is an implementation detail that
+  // the server adds based on the active employee — the user should never see it.
+  // Store the job ID as a pending coaching job. The #coach-note shows a
+  // human-readable label; the textarea stays focused for optional extra context.
+  // When the user clicks Send, continueRun sends { coachingJobId, instructions }.
+  const label = managerJobId.split('-').map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  // Strip any prior /fraim invocation text already in the textarea (backward-compat
+  // for sessions that stored raw invocation text before this change).
   const textarea = els['coach-text'];
-  const prior = textarea.value;
-  let combined;
-  if (prior.trim().length === 0) {
-    combined = invocation;
-  } else {
-    const strippedPrior = prior.replace(/(?:^|\n|\s)[/$]fraim\s+[a-z0-9-]+(?:\s|$)/ig, ' ').replace(/\s+/g, ' ').trim();
-    combined = strippedPrior ? `${invocation}\n\n${strippedPrior}` : invocation;
-  }
-  textarea.value = combined;
-  // Caret at the end.
-  textarea.setSelectionRange(combined.length, combined.length);
+  textarea.value = textarea.value
+    .replace(/(?:^|\n|\s)[/$]fraim\s+[a-z0-9-]+(?:\s|$)/ig, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
   textarea.focus();
-  syncSendButton();
+  setPendingCoachingJob(managerJobId, label);
   closeTemplatePopover();
 }
 
@@ -1326,20 +1474,6 @@ function surfaceText(role, text, conv) {
   return raw;
 }
 
-function extractExplicitFraimInvocation(text) {
-  const raw = String(text || '');
-  const match = raw.match(/(?:^|\n|\s)([$/]fraim)\s+([a-z0-9][a-z0-9-]*)(?=\s|$)/i);
-  if (!match || match.index == null) return null;
-  const before = raw.slice(0, match.index).trim();
-  const after = raw.slice(match.index + match[0].length).trim();
-  const remainder = [before, after].filter(Boolean).join('\n\n').trim();
-  return {
-    symbol: match[1],
-    jobId: match[2],
-    remainder,
-  };
-}
-
 function latestEmployeeSurfaceText(conv) {
   const messages = conv.messages || [];
   for (let i = messages.length - 1; i >= 0; i -= 1) {
@@ -1449,7 +1583,39 @@ function syncSendButton() {
   // coach mid-run (which is exactly what /api/ai-hub/runs/:id/messages
   // is for; the server only requires sessionId).
   const resumable = !!(conv && conv.sessionId);
-  els['send'].disabled = !(hasText && resumable);
+  // A pending coaching job (set by quick-coach buttons or template picker)
+  // is enough to enable Send even with an empty textarea — the user just
+  // wants to fire that coaching directive, optionally with added context.
+  const hasPendingJob = !!state.pendingCoachingJobId;
+  els['send'].disabled = !((hasText || hasPendingJob) && resumable);
+}
+
+// ---------------------------------------------------------------------------
+// Pending coaching job helpers
+// ---------------------------------------------------------------------------
+
+// Set a pending coaching job selected via a quick-coach button or template
+// picker. The invocation is NOT put into the textarea — the server adds it
+// based on the active employee. The coach-note shows a human-readable label
+// so the user knows what will fire when they hit Send.
+function setPendingCoachingJob(jobId, label) {
+  state.pendingCoachingJobId = jobId;
+  state.pendingCoachingLabel = label;
+  if (els['coach-note']) {
+    els['coach-note'].textContent = `▶ ${label} — add context below (optional) then send`;
+    els['coach-note'].classList.add('pending-job');
+  }
+  syncSendButton();
+}
+
+function clearPendingCoachingJob() {
+  state.pendingCoachingJobId = null;
+  state.pendingCoachingLabel = null;
+  if (els['coach-note']) {
+    els['coach-note'].classList.remove('pending-job');
+    // Note text is restored to normal status by the next renderActive call.
+  }
+  syncSendButton();
 }
 
 // ---------------------------------------------------------------------------
@@ -1897,50 +2063,22 @@ function deriveTitle(jobTitle, instructions) {
 //     (per developers.openai.com/codex/skills: "type $ to mention a skill")
 //   - Project-canonical mapping at src/cli/setup/ide-invocation-surfaces.ts.
 //
-// Every command typed by the manager is prefixed with the agent's FRAIM
-// symbol so the host always sees that this is a FRAIM job, not a freeform
-// prompt. Follow-up coaching keeps the jobId too; otherwise headless hosts
-// lose which FRAIM workflow the manager meant to run.
-const FRAIM_INVOCATION_SYMBOL = {
-  codex: '$fraim',
-  claude: '/fraim',
-  gemini: '/fraim',
-};
-
-function fraimInvocationFor(employeeId, jobId, kind) {
-  if (jobId === '__freeform__') return null;
-  const symbol = FRAIM_INVOCATION_SYMBOL[employeeId] || '/fraim';
-  return `${symbol} ${jobId}`;
-}
-
-// Wrap the manager's typed instructions with the host-appropriate FRAIM
-// invocation. The wrapped text is what we ACTUALLY send to the host CLI
-// AND what we show in the timeline so the manager sees what the agent
-// received. For freeform jobs (no FRAIM job assigned), the instructions
-// are sent verbatim with no invocation prefix.
-function buildAgentMessage(employeeId, jobId, kind, instructions, stubPath) {
-  const trimmed = (instructions || '').trim();
-  const explicit = extractExplicitFraimInvocation(trimmed);
-  const effectiveJobId = explicit?.jobId || jobId;
-  const invocation = fraimInvocationFor(employeeId, effectiveJobId, kind);
-  // Freeform: no FRAIM prefix, no stub reference — just the raw instructions.
-  if (!invocation) return explicit?.remainder || trimmed;
-  const remainder = explicit ? explicit.remainder : trimmed;
-  const stub = (kind === 'start' && stubPath) ? `\n[Job stub: ${stubPath}]` : '';
-  if (!remainder) return `${invocation}${stub}`;
-  return `${invocation}${stub}\n\n${remainder}`;
-}
-
+// The browser sends raw manager instructions. AI Hub normalizes assigned
+// FRAIM jobs into host-facing invocations so the Hub UI and channel callers
+// share one start/continue contract.
 async function startRun(job, instructions, employeeId) {
-  // Prefix the manager's typed instructions with the FRAIM invocation so
-  // the underlying host actually launches the right job. The prefixed
-  // text is what the host receives AND what we show in the timeline.
-  // Freeform jobs carry no job stub and no FRAIM invocation prefix.
   const isFreeform = job.id === '__freeform__';
-  const absoluteStubPath = (!isFreeform && job.stubPath && state.projectPath)
-    ? [state.projectPath, job.stubPath].join('/').replace(/\\/g, '/').replace(/\/+/g, '/')
-    : undefined;
-  const agentMessage = buildAgentMessage(employeeId, job.id, 'start', instructions, absoluteStubPath);
+  // In task-pane/extension mode: get a fresh selection snapshot and prepend
+  // document context to the instructions so the agent knows what the user is
+  // looking at. stubPath resolution and FRAIM invocation are now server-side.
+  let effectiveInstructions = instructions || '';
+  if (document.body.dataset.surface === 'task-pane' || document.body.dataset.surface === 'extension') {
+    const fresh = await requestWordContext('get-selection').catch(() => null);
+    const wc = (fresh && (fresh.selection || fresh.hasSelection)) ? { ...state.wordContext, ...fresh } : state.wordContext;
+    const ctxBlock = buildWordContextBlock(wc);
+    if (ctxBlock) effectiveInstructions = ctxBlock + '\n\n---\n\n' + effectiveInstructions;
+  }
+
   // Issue #442: read the A/B toggle state from the modal before it closes.
   const abToggle = document.getElementById('ab-toggle');
   const isAB = !isFreeform && abToggle && abToggle.checked;
@@ -1957,7 +2095,7 @@ async function startRun(job, instructions, employeeId) {
     runId: null,
     sessionId: null,
     status: 'running',
-    messages: [{ role: 'manager', text: agentMessage, at: Date.now() }],
+    messages: [],
     events: [],
     artifacts: [],
     lastUpdatedAt: Date.now(),
@@ -1965,6 +2103,8 @@ async function startRun(job, instructions, employeeId) {
     compareMode: isAB ? 'ab' : undefined,
     compareRunId: null,
     compareRun: null,
+    // Issue #489: capture selection state at job-start so write-back knows insert-after vs append.
+    wordStartedWithSelection: document.body.dataset.surface === 'task-pane' && !!(state.wordContext && state.wordContext.hasSelection),
   };
   upsertConversation(conv);
   state.activeId = conv.id;
@@ -1980,8 +2120,8 @@ async function startRun(job, instructions, employeeId) {
         projectPath: state.projectPath,
         hostId: employeeId,
         jobId: job.id,
-        message: agentMessage,
-        ...(isAB ? { compareMode: 'ab', directInstructions: instructions } : {}),
+        instructions: effectiveInstructions,
+        ...(isAB ? { compareMode: 'ab', directInstructions: effectiveInstructions } : {}),
       }),
     });
     conv.runId = run.id;
@@ -2008,10 +2148,14 @@ async function startRun(job, instructions, employeeId) {
 // Start a NEW run on an existing conversation with a different agent.
 // The conversation's message history stays intact; only the run restarts.
 async function restartConvWithAgent(conv, newAgentId, text) {
-  const agentMessage = buildAgentMessage(newAgentId, conv.jobId, 'start', text);
+  // Snapshot both the message history and the event log so they survive the
+  // restart. foldRunIntoConversation replaces these arrays on every call
+  // (including poll ticks), so we must store them on the conv object itself —
+  // not as local variables that only live until the first poll fires.
+  conv._priorMessages = Array.isArray(conv.messages) ? [...conv.messages] : [];
+  conv._priorEvents = Array.isArray(conv.events) ? [...conv.events] : [];
   conv.status = 'running';
   conv.sessionId = null;
-  conv.messages.push({ role: 'manager', text: agentMessage, at: Date.now() });
   upsertConversation(conv);
   renderRail();
   renderActive();
@@ -2023,11 +2167,13 @@ async function restartConvWithAgent(conv, newAgentId, text) {
         projectPath: state.projectPath,
         hostId: newAgentId,
         jobId: conv.jobId,
-        message: agentMessage,
+        instructions: text,
       }),
     });
     conv.runId = run.id;
     foldRunIntoConversation(conv, run);
+    // Note: foldRunIntoConversation now prepends _priorMessages/_priorEvents
+    // on every call, so the history is preserved through poll ticks too.
     upsertConversation(conv);
     renderRail();
     renderActive();
@@ -2045,11 +2191,12 @@ async function restartConvWithAgent(conv, newAgentId, text) {
 async function continueRun(text) {
   const conv = activeConversation();
   if (!conv || !conv.runId) return;
-  // Prefix follow-up coaching with @fraim so the host knows this is a
-  // continuation of the active FRAIM session rather than a fresh prompt.
-  const agentMessage = buildAgentMessage(conv.employeeId, conv.jobId, 'continue', text);
+  // Consume any pending coaching job selected via quick-coach or template picker.
+  // The server adds the correct invocation prefix ($fraim / /fraim) based on
+  // the active employee — the user never sees raw invocation syntax.
+  const coachingJobId = state.pendingCoachingJobId || undefined;
+  clearPendingCoachingJob();
   conv.status = 'running';
-  conv.messages.push({ role: 'manager', text: agentMessage, at: Date.now() });
   upsertConversation(conv);
   renderRail();
   renderActive();
@@ -2057,7 +2204,7 @@ async function continueRun(text) {
     const run = await requestJson(`/api/ai-hub/runs/${conv.runId}/messages`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ message: agentMessage }),
+      body: JSON.stringify({ instructions: text, ...(coachingJobId ? { coachingJobId } : {}) }),
     });
     foldRunIntoConversation(conv, run);
     upsertConversation(conv);
@@ -2086,15 +2233,19 @@ function foldRunIntoConversation(conv, run) {
     totals: run.totals || null,
   };
   // Replace the conversation's events with the run's events (single source of truth on the server).
-  conv.events = (run.events || []).map((e) => ({ channel: e.channel, text: e.text }));
-  // Append any employee messages we don't already have.
-  const existingEmployeeTexts = new Set(conv.messages.filter((m) => m.role === 'employee').map((m) => m.text));
-  for (const m of run.messages || []) {
-    if (m.role === 'employee' && !existingEmployeeTexts.has(m.text)) {
-      conv.messages.push({ role: 'employee', text: m.text, at: Date.now() });
-      existingEmployeeTexts.add(m.text);
-    }
-  }
+  // If this conversation was restarted on a different agent, prepend the prior run's events so
+  // the micro-log shows the full diagnostic history across all run attempts (Issue #495).
+  const newEvents = (run.events || []).map((e) => ({ channel: e.channel, text: e.text }));
+  const priorEvents = Array.isArray(conv._priorEvents) ? conv._priorEvents : [];
+  conv.events = priorEvents.length > 0 ? [...priorEvents, ...newEvents] : newEvents;
+  // Same treatment for messages: prepend any cross-run history captured at restart time.
+  const newMessages = (run.messages || []).map((m) => ({
+    role: m.role,
+    text: m.text,
+    at: Date.parse(m.createdAt) || Date.now(),
+  }));
+  const priorMessages = Array.isArray(conv._priorMessages) ? conv._priorMessages : [];
+  conv.messages = priorMessages.length > 0 ? [...priorMessages, ...newMessages] : newMessages;
   // Track session for resumption.
   if (run.sessionId) conv.sessionId = run.sessionId;
   // R4: persist the persona key from the server-side run record.
@@ -2179,6 +2330,7 @@ function startPolling() {
       if (nowFraimDone && nowDirectDone) {
         window.clearInterval(state.pollHandle);
         state.pollHandle = null;
+        tryWordWriteBack(conv);
       }
     } catch (error) {
       console.warn('Polling failed:', error);
@@ -2186,6 +2338,35 @@ function startPolling() {
   }, 1000);
 }
 
+// Issue #489: When a job completes in Word task-pane surface, write the final
+// agent output back into the document with tracked changes so the user can
+// accept/reject via Word's normal review flow.
+async function tryWordWriteBack(conv) {
+  if (conv.wordWrittenBack) return;
+  if (document.body.dataset.surface !== 'task-pane') return;
+  if (!state.wordContext || !state.wordContext.docTitle) return;
+  if (conv.status !== 'completed') return;
+
+  const employeeMessages = (conv.messages || []).filter(m => m.role === 'employee');
+  if (employeeMessages.length === 0) return;
+  const outputText = employeeMessages[employeeMessages.length - 1].text;
+  if (!outputText || !outputText.trim()) return;
+
+  // Mark before async calls to guard against concurrent poll ticks.
+  conv.wordWrittenBack = true;
+  upsertConversation(conv);
+
+  try {
+    await requestWordContext('track-changes-on');
+    const action = conv.wordStartedWithSelection ? 'insert-after' : 'append-to-doc';
+    await requestWordContext(action, { text: outputText });
+    await requestWordContext('track-changes-off');
+    showStatus('Result written to document — review tracked changes in Word.');
+  } catch (e) {
+    console.warn('Word write-back failed:', e);
+  }
+}
+
 function convNeedsPolling(conv) {
   if (!conv || !conv.runId) return false;
   const fraimRunning = conv.status === 'running';
@@ -2218,11 +2399,9 @@ function showStatus(text, isError) {
 
 async function pickProject() {
   try {
-    const response = await fetch('/api/ai-hub/project-path/pick', { method: 'POST' });
-    if (response.status === 204) return;
-    const payload = await response.json();
-    if (!response.ok) throw new Error(payload.error || 'Could not choose a folder.');
-    if (payload.path) {
+    // 204 = user cancelled the OS folder picker; requestJson returns null for empty bodies.
+    const payload = await requestJson('/api/ai-hub/project-path/pick', { method: 'POST' });
+    if (payload && payload.path) {
       await loadBootstrap(payload.path);
     }
   } catch (error) {
@@ -2252,6 +2431,7 @@ function showStep2(job) {
   els['start'].disabled = true;
   els['step1'].hidden = true;
   els['step2'].hidden = false;
+  renderWordContextInModal();
   setTimeout(() => els['instructions'].focus(), 50);
 }
 
@@ -2307,7 +2487,9 @@ function wireEvents() {
   els['coach-text'].addEventListener('input', syncSendButton);
   els['send'].addEventListener('click', async () => {
     const text = els['coach-text'].value.trim();
-    if (!text) return;
+    // Allow send when textarea is empty IFF a coaching job is pending — the
+    // user clicked a quick-coach button and just wants to fire that job.
+    if (!text && !state.pendingCoachingJobId) return;
     els['coach-text'].value = '';
     syncSendButton();
     // If the user changed the agent via the inline selector, restart with the
@@ -2402,22 +2584,19 @@ function wireEvents() {
   }
 
   // R5: quick-access coaching buttons.
+  // The invocation syntax ($fraim / /fraim) stays out of the UI entirely —
+  // the server adds it based on the active employee. Clicking a button sets a
+  // pending coaching job (shown in #coach-note); the user can add optional
+  // context in the textarea and then click Send.
   if (els['quick-coach-btns']) {
     els['quick-coach-btns'].addEventListener('click', (e) => {
       const btn = e.target.closest('.quick-coach-btn');
       if (!btn) return;
       const jobId = btn.dataset.job;
       if (!jobId) return;
-      const conv = activeConversation();
-      const prefix = conv && conv.employeeId && conv.employeeId.toLowerCase().includes('codex') ? '$fraim' : '/fraim';
-      const invocation = `${prefix} ${jobId}`;
-      const textarea = els['coach-text'];
-      const existing = textarea.value;
-      const sep = existing && !existing.endsWith(' ') ? ' ' : '';
-      textarea.value = existing + sep + invocation;
-      textarea.focus();
-      textarea.setSelectionRange(textarea.value.length, textarea.value.length);
-      syncSendButton();
+      const label = btn.textContent.trim();
+      setPendingCoachingJob(jobId, label);
+      els['coach-text'].focus();
     });
   }
   if (els['other-manager-jobs-btn']) {
@@ -2459,6 +2638,24 @@ function wireEvents() {
   }
   bindEnterToButton(els['coach-text'], els['send']);
   bindEnterToButton(els['instructions'], els['start']);
+
+  // Word context bar refresh button.
+  if (els['word-ctx-refresh']) {
+    els['word-ctx-refresh'].addEventListener('click', async () => {
+      const fresh = await requestWordContext('get-context');
+      if (fresh) { state.wordContext = fresh; renderWordContextBar(); renderWordContextInModal(); }
+    });
+  }
+  // Word context card expand/collapse toggle.
+  if (els['word-ctx-card-toggle']) {
+    els['word-ctx-card-toggle'].addEventListener('click', () => {
+      const body = els['word-ctx-card-body'];
+      if (!body) return;
+      const expanded = !body.hidden;
+      body.hidden = expanded;
+      els['word-ctx-card-toggle'].textContent = expanded ? '▸' : '▾';
+    });
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -2466,6 +2663,9 @@ function wireEvents() {
 // ---------------------------------------------------------------------------
 
 (async function init() {
+  // html.electron is already set by the inline script in <head> for zero-flash.
+  // This is a belt-and-suspenders fallback in case the inline script was skipped.
+
   gatherElements();
   loadConversationsFromStorage();
   wirePopovers();
@@ -2473,14 +2673,34 @@ function wireEvents() {
 
   const urlParams = new URLSearchParams(window.location.search);
   const isFirstRun = urlParams.get('firstRun') === 'true';
+  const surface = urlParams.get('surface') || 'hub';
+  const docUrl = urlParams.get('docUrl') || '';
+
+  // Apply surface class before bootstrap so CSS takes effect immediately.
+  if (surface !== 'hub') document.body.dataset.surface = surface;
+
+  // Register the Word context bridge (no-op outside iframe context).
+  setupWordBridge();
 
   try {
-    await loadBootstrap();
+    await loadBootstrap(null, docUrl);
   } catch (error) {
     showStatus(error.message, true);
     return;
   }
 
+  // Task-pane and extension surfaces: skip welcome/onboarding, show active job
+  // or open the new-job picker. Layout is compact (rail hidden via CSS).
+  if (surface === 'task-pane' || surface === 'extension') {
+    const conv = activeConversation();
+    if (conv && conv.projectPath === state.projectPath) {
+      if (convNeedsPolling(conv)) startPolling();
+    } else {
+      openModal();
+    }
+    return;
+  }
+
   if (isFirstRun) {
     renderFirstRunLanding();
     return;
@@ -2621,11 +2841,8 @@ function renderFirstRunLanding(mode) {
   ].join('');
   browseBtn.addEventListener('click', async () => {
     try {
-      const response = await fetch('/api/ai-hub/project-path/pick', { method: 'POST' });
-      if (response.status === 204) return;
-      const payload = await response.json();
-      if (!response.ok) throw new Error(payload.error || 'Could not pick folder.');
-      if (payload.path) {
+      const payload = await requestJson('/api/ai-hub/project-path/pick', { method: 'POST' });
+      if (payload && payload.path) {
         await loadBootstrap(payload.path);
         folderInput.value = state.projectPath;
         folderInput.style.color = 'var(--text,#1f2a24)';