Interview (#262)

* Interview

* Interview

* Fix tests

* Fix test isolation in auto-update-checker tests

Refactored checker.test.ts to use the same dynamic import pattern with
cache busting that cache.test.ts uses, and replaced mock.module('node:fs')
with spyOn for proper test isolation.

Changes:
- checker.test.ts: Use dynamic imports with cache busting and spyOn for fs
- cache.test.ts: Add missing getOpenCodeConfigPaths mock
- index.test.ts: Use dynamic imports with cache busting

This ensures tests don't interfere with each other when running the full suite.

* Fix test isolation in auto-update-checker and update interview prompts

* Add configurable interview resumes and browser launch

* Polish interview UI and refresh docs

* Fix interview submission locking race

* Fix interview review follow-ups

README.md

@@ -358,6 +358,7 @@ If any agent fails to respond, check your provider authentication and config fil
 | Feature | Doc | What it does |
 |---------|-----|--------------|
 | **Council** | [council.md](docs/council.md) | Run N models in parallel, synthesize one answer (`@council`) |
+| **Interview** | [interview.md](docs/interview.md) | Browser-based Q&A flow for turning rough ideas into a live markdown spec |
 | **Multiplexer Integration** | [multiplexer-integration.md](docs/multiplexer-integration.md) | Watch agents work in real-time with auto-spawned panes (Tmux/Zellij) |
 | **Cartography Skill** | [cartography.md](docs/cartography.md) | Auto-generate hierarchical codemaps for any codebase |
 

docs/interview.md

@@ -0,0 +1,150 @@
+# Interview
+
+`/interview` opens a local browser UI for refining a feature idea inside the same OpenCode session.
+
+Use it when chat feels too loose and you want a cleaner question/answer flow plus a markdown spec saved in your repo.
+
+> Tip: `/interview` usually works well with a fast model. If the flow feels slower than it should, switch models in OpenCode with `Ctrl+X`, then `m`, and pick a faster one.
+
+## Quick start
+
+Start a new interview:
+
+```text
+/interview build a kanban app for design teams
+```
+
+What happens:
+
+1. OpenCode starts the interview in your current session
+2. a localhost page opens in your browser by default
+3. the UI shows the current questions and suggested answers
+4. answers are submitted back into the same session
+5. a markdown spec is updated in your repo
+
+OpenCode posts a localhost URL like this:
+
+![Interview URL](../img/interview-url.png)
+
+And the browser UI looks like this:
+
+![Interview website](../img/interview-website.png)
+
+Resume an existing interview:
+
+```text
+/interview interview/kanban-design-tool.md
+```
+
+You can also resume by basename if it exists in the configured output folder:
+
+```text
+/interview kanban-design-tool
+```
+
+## What the browser UI gives you
+
+- focused question flow instead of open-ended chat
+- suggested answers, clearly marked as recommended
+- keyboard-driven selection for the active question
+- custom freeform answers when needed
+- visible path to the markdown interview file
+- larger, more readable interview UI
+
+## Markdown output
+
+By default, interview files are written to:
+
+```text
+interview/
+```
+
+Example:
+
+```text
+interview/kanban-design-tool.md
+```
+
+The file contains two sections:
+
+- `Current spec` — rewritten as the interview becomes clearer
+- `Q&A history` — append-only question/answer record
+
+Example:
+
+```md
+# Kanban App For Design Teams
+
+## Current spec
+
+A collaborative kanban tool for design teams with shared boards, comments, and web-first workflows.
+
+## Q&A history
+
+Q: Who is this for?
+A: Design teams
+
+Q: Is this web only or mobile too?
+A: Web first
+```
+
+### How filenames are chosen
+
+For new interviews, the assistant can suggest a concise title for the markdown filename.
+
+Example:
+
+- user input: `build a kanban app for design teams with lightweight reviews`
+- file: `interview/kanban-design-tool.md`
+
+If the assistant does not provide a title, the original input is slugified as a fallback.
+
+## Keyboard shortcuts
+
+Inside the interview page:
+
+- `1`, `2`, `3`, ... select options for the active question
+- the last number selects `Custom`
+- `↑` / `↓` move the active question
+- `Cmd+Enter` or `Ctrl+Enter` submits
+- `Cmd+S` or `Ctrl+S` also submits
+
+## Configuration
+
+```jsonc
+{
+  "oh-my-opencode-slim": {
+    "interview": {
+      "maxQuestions": 2,
+      "outputFolder": "interview",
+      "autoOpenBrowser": true
+    }
+  }
+}
+```
+
+### Options
+
+- `maxQuestions` — max questions per round, `1-10`, default `2`
+- `outputFolder` — where markdown files are written, default `interview`
+- `autoOpenBrowser` — open the localhost UI in your default browser, default `true`
+
+## Good use cases
+
+- feature planning
+- requirement clarification before implementation
+- turning a rough idea into a spec the agent can build from
+- keeping a lightweight product brief in the repo while iterating
+
+## Current limitations
+
+- localhost UI only
+- browser updates use polling, not realtime push
+- runtime interview state is in-memory; the markdown file is the durable artifact
+- the flow depends on the assistant returning valid `<interview_state>` blocks
+
+## Related
+
+- [README.md](../README.md)
+- [tools.md](tools.md)
+- [configuration.md](configuration.md)

oh-my-opencode-slim.schema.json

@@ -413,6 +413,26 @@
         }
       }
     },
+    "interview": {
+      "type": "object",
+      "properties": {
+        "maxQuestions": {
+          "default": 2,
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "outputFolder": {
+          "default": "interview",
+          "type": "string",
+          "minLength": 1
+        },
+        "autoOpenBrowser": {
+          "default": true,
+          "type": "boolean"
+        }
+      }
+    },
     "todoContinuation": {
       "type": "object",
       "properties": {

src/config/loader.ts

@@ -163,6 +163,7 @@ export function loadPluginConfig(directory: string): PluginConfig {
       agents: deepMerge(config.agents, projectConfig.agents),
       tmux: deepMerge(config.tmux, projectConfig.tmux),
       multiplexer: deepMerge(config.multiplexer, projectConfig.multiplexer),
+      interview: deepMerge(config.interview, projectConfig.interview),
       fallback: deepMerge(config.fallback, projectConfig.fallback),
       council: deepMerge(config.council, projectConfig.council),
     };

src/config/schema.ts

@@ -164,6 +164,14 @@ export const BackgroundTaskConfigSchema = z.object({
 
 export type BackgroundTaskConfig = z.infer<typeof BackgroundTaskConfigSchema>;
 
+export const InterviewConfigSchema = z.object({
+  maxQuestions: z.number().int().min(1).max(10).default(2),
+  outputFolder: z.string().min(1).default('interview'),
+  autoOpenBrowser: z.boolean().default(true),
+});
+
+export type InterviewConfig = z.infer<typeof InterviewConfigSchema>;
+
 // Todo continuation configuration
 export const TodoContinuationConfigSchema = z.object({
   maxContinuations: z
@@ -236,6 +244,7 @@ export const PluginConfigSchema = z.object({
   tmux: TmuxConfigSchema.optional(),
   websearch: WebsearchConfigSchema.optional(),
   background: BackgroundTaskConfigSchema.optional(),
+  interview: InterviewConfigSchema.optional(),
   todoContinuation: TodoContinuationConfigSchema.optional(),
   fallback: FailoverConfigSchema.optional(),
   council: CouncilConfigSchema.optional(),

src/hooks/auto-update-checker/cache.test.ts

@@ -1,58 +1,59 @@
-import { describe, expect, mock, test } from 'bun:test';
+import { describe, expect, mock, spyOn, test } from 'bun:test';
 import * as fs from 'node:fs';
-import { invalidatePackage } from './cache';
 
-// Mock internal dependencies
-mock.module('./constants', () => ({
-  CACHE_DIR: '/mock/cache',
-  PACKAGE_NAME: 'oh-my-opencode-slim',
-}));
-
-mock.module('../../shared/logger', () => ({
+// Mock logger to avoid noise
+mock.module('../../utils/logger', () => ({
   log: mock(() => {}),
 }));
 
-// Mock fs and path
-mock.module('node:fs', () => ({
-  existsSync: mock(() => false),
-  rmSync: mock(() => {}),
-  readFileSync: mock(() => ''),
-  writeFileSync: mock(() => {}),
-}));
-
 mock.module('../../cli/config-manager', () => ({
   stripJsonComments: (s: string) => s,
+  getOpenCodeConfigPaths: () => [
+    '/mock/config/opencode.json',
+    '/mock/config/opencode.jsonc',
+  ],
 }));
 
+// Cache buster for dynamic imports
+let importCounter = 0;
+
 describe('auto-update-checker/cache', () => {
   describe('invalidatePackage', () => {
-    test('returns false when nothing to invalidate', () => {
-      const existsMock = fs.existsSync as any;
-      existsMock.mockReturnValue(false);
+    test('returns false when nothing to invalidate', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(false);
+      const { invalidatePackage } = await import(
+        `./cache?test=${importCounter++}`
+      );
 
       const result = invalidatePackage();
       expect(result).toBe(false);
-    });
 
-    test('returns true and removes directory if node_modules path exists', () => {
-      const existsMock = fs.existsSync as any;
-      const rmSyncMock = fs.rmSync as any;
+      existsSpy.mockRestore();
+    });
 
-      existsMock.mockImplementation((p: string) => p.includes('node_modules'));
+    test('returns true and removes directory if node_modules path exists', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockImplementation(
+        (p: string) => p.includes('node_modules'),
+      );
+      const rmSyncSpy = spyOn(fs, 'rmSync').mockReturnValue(undefined);
+      const { invalidatePackage } = await import(
+        `./cache?test=${importCounter++}`
+      );
 
       const result = invalidatePackage();
 
-      expect(rmSyncMock).toHaveBeenCalled();
+      expect(rmSyncSpy).toHaveBeenCalled();
       expect(result).toBe(true);
-    });
 
-    test('removes dependency from package.json if present', () => {
-      const existsMock = fs.existsSync as any;
-      const readMock = fs.readFileSync as any;
-      const writeMock = fs.writeFileSync as any;
+      existsSpy.mockRestore();
+      rmSyncSpy.mockRestore();
+    });
 
-      existsMock.mockImplementation((p: string) => p.includes('package.json'));
-      readMock.mockReturnValue(
+    test('removes dependency from package.json if present', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockImplementation(
+        (p: string) => p.includes('package.json'),
+      );
+      const readSpy = spyOn(fs, 'readFileSync').mockReturnValue(
         JSON.stringify({
           dependencies: {
             'oh-my-opencode-slim': '1.0.0',
@@ -60,14 +61,27 @@ describe('auto-update-checker/cache', () => {
           },
         }),
       );
+      const writtenData: string[] = [];
+      const writeSpy = spyOn(fs, 'writeFileSync').mockImplementation(
+        (_path: string, data: string) => {
+          writtenData.push(data);
+        },
+      );
+      const { invalidatePackage } = await import(
+        `./cache?test=${importCounter++}`
+      );
 
       const result = invalidatePackage();
 
       expect(result).toBe(true);
-      const callArgs = writeMock.mock.calls[0];
-      const savedJson = JSON.parse(callArgs[1]);
+      expect(writtenData.length).toBeGreaterThan(0);
+      const savedJson = JSON.parse(writtenData[0]);
       expect(savedJson.dependencies['oh-my-opencode-slim']).toBeUndefined();
       expect(savedJson.dependencies['other-pkg']).toBe('1.0.0');
+
+      existsSpy.mockRestore();
+      readSpy.mockRestore();
+      writeSpy.mockRestore();
     });
   });
 });

src/hooks/auto-update-checker/checker.test.ts

@@ -1,116 +1,152 @@
-import { describe, expect, mock, test } from 'bun:test';
+import { describe, expect, mock, spyOn, test } from 'bun:test';
 import * as fs from 'node:fs';
-import { extractChannel, findPluginEntry, getLocalDevVersion } from './checker';
-
-// Mock the dependencies
-mock.module('./constants', () => ({
-  PACKAGE_NAME: 'oh-my-opencode-slim',
-  USER_OPENCODE_CONFIG: '/mock/config/opencode.json',
-  USER_OPENCODE_CONFIG_JSONC: '/mock/config/opencode.jsonc',
-  INSTALLED_PACKAGE_JSON:
-    '/mock/cache/node_modules/oh-my-opencode-slim/package.json',
+
+// Mock logger to avoid noise
+mock.module('../../utils/logger', () => ({
+  log: mock(() => {}),
 }));
 
-mock.module('node:fs', () => ({
-  existsSync: mock((_p: string) => false),
-  readFileSync: mock((_p: string) => ''),
-  statSync: mock((_p: string) => ({ isDirectory: () => true })),
-  writeFileSync: mock(() => {}),
+mock.module('../../cli/config-manager', () => ({
+  stripJsonComments: (s: string) => s,
+  getOpenCodeConfigPaths: () => [
+    '/mock/config/opencode.json',
+    '/mock/config/opencode.jsonc',
+  ],
 }));
 
+// Cache buster for dynamic imports
+let importCounter = 0;
+
 describe('auto-update-checker/checker', () => {
   describe('extractChannel', () => {
-    test('returns latest for null or empty', () => {
+    test('returns latest for null or empty', async () => {
+      const { extractChannel } = await import(
+        `./checker?test=${importCounter++}`
+      );
       expect(extractChannel(null)).toBe('latest');
       expect(extractChannel('')).toBe('latest');
     });
 
-    test('returns tag if version starts with non-digit', () => {
+    test('returns tag if version starts with non-digit', async () => {
+      const { extractChannel } = await import(
+        `./checker?test=${importCounter++}`
+      );
       expect(extractChannel('beta')).toBe('beta');
       expect(extractChannel('next')).toBe('next');
     });
 
-    test('extracts channel from prerelease version', () => {
+    test('extracts channel from prerelease version', async () => {
+      const { extractChannel } = await import(
+        `./checker?test=${importCounter++}`
+      );
       expect(extractChannel('1.0.0-alpha.1')).toBe('alpha');
       expect(extractChannel('2.3.4-beta.5')).toBe('beta');
       expect(extractChannel('0.1.0-rc.1')).toBe('rc');
       expect(extractChannel('1.0.0-canary.0')).toBe('canary');
     });
 
-    test('returns latest for standard versions', () => {
+    test('returns latest for standard versions', async () => {
+      const { extractChannel } = await import(
+        `./checker?test=${importCounter++}`
+      );
       expect(extractChannel('1.0.0')).toBe('latest');
     });
   });
 
   describe('getLocalDevVersion', () => {
-    test('returns null if no local dev path in config', () => {
-      // existsSync returns false by default from mock
+    test('returns null if no local dev path in config', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockReturnValue(false);
+      const { getLocalDevVersion } = await import(
+        `./checker?test=${importCounter++}`
+      );
+
       expect(getLocalDevVersion('/test')).toBeNull();
+
+      existsSpy.mockRestore();
     });
 
-    test('returns version from local package.json if path exists', () => {
-      const existsMock = fs.existsSync as any;
-      const readMock = fs.readFileSync as any;
-
-      existsMock.mockImplementation((p: string) => {
-        if (p.includes('opencode.json')) return true;
-        if (p.includes('package.json')) return true;
-        return false;
-      });
-
-      readMock.mockImplementation((p: string) => {
-        if (p.includes('opencode.json')) {
-          return JSON.stringify({
-            plugin: ['file:///dev/oh-my-opencode-slim'],
-          });
-        }
-        if (p.includes('package.json')) {
-          return JSON.stringify({
-            name: 'oh-my-opencode-slim',
-            version: '1.2.3-dev',
-          });
-        }
-        return '';
-      });
+    test('returns version from local package.json if path exists', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockImplementation(
+        (p: string) => {
+          if (p.includes('opencode.json')) return true;
+          if (p.includes('package.json')) return true;
+          return false;
+        },
+      );
+      const readSpy = spyOn(fs, 'readFileSync').mockImplementation(
+        (p: string) => {
+          if (p.includes('opencode.json')) {
+            return JSON.stringify({
+              plugin: ['file:///dev/oh-my-opencode-slim'],
+            });
+          }
+          if (p.includes('package.json')) {
+            return JSON.stringify({
+              name: 'oh-my-opencode-slim',
+              version: '1.2.3-dev',
+            });
+          }
+          return '';
+        },
+      );
+
+      const { getLocalDevVersion } = await import(
+        `./checker?test=${importCounter++}`
+      );
 
       expect(getLocalDevVersion('/test')).toBe('1.2.3-dev');
+
+      existsSpy.mockRestore();
+      readSpy.mockRestore();
     });
   });
 
   describe('findPluginEntry', () => {
-    test('detects latest version entry', () => {
-      const existsMock = fs.existsSync as any;
-      const readMock = fs.readFileSync as any;
-
-      existsMock.mockImplementation((p: string) => p.includes('opencode.json'));
-      readMock.mockImplementation(() =>
+    test('detects latest version entry', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockImplementation(
+        (p: string) => p.includes('opencode.json'),
+      );
+      const readSpy = spyOn(fs, 'readFileSync').mockReturnValue(
         JSON.stringify({
           plugin: ['oh-my-opencode-slim'],
         }),
       );
 
+      const { findPluginEntry } = await import(
+        `./checker?test=${importCounter++}`
+      );
+
       const entry = findPluginEntry('/test');
       expect(entry).not.toBeNull();
       expect(entry?.entry).toBe('oh-my-opencode-slim');
       expect(entry?.isPinned).toBe(false);
       expect(entry?.pinnedVersion).toBeNull();
-    });
 
-    test('detects pinned version entry', () => {
-      const existsMock = fs.existsSync as any;
-      const readMock = fs.readFileSync as any;
+      existsSpy.mockRestore();
+      readSpy.mockRestore();
+    });
 
-      existsMock.mockImplementation((p: string) => p.includes('opencode.json'));
-      readMock.mockImplementation(() =>
+    test('detects pinned version entry', async () => {
+      const existsSpy = spyOn(fs, 'existsSync').mockImplementation(
+        (p: string) => p.includes('opencode.json'),
+      );
+      const readSpy = spyOn(fs, 'readFileSync').mockReturnValue(
         JSON.stringify({
           plugin: ['oh-my-opencode-slim@1.0.0'],
         }),
       );
 
+      const { findPluginEntry } = await import(
+        `./checker?test=${importCounter++}`
+      );
+
       const entry = findPluginEntry('/test');
       expect(entry).not.toBeNull();
       expect(entry?.isPinned).toBe(true);
       expect(entry?.pinnedVersion).toBe('1.0.0');
+
+      existsSpy.mockRestore();
+      readSpy.mockRestore();
     });
   });
 });

src/hooks/auto-update-checker/index.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, mock, test } from 'bun:test';
 
-mock.module('./constants', () => ({
-  CACHE_DIR: '/mock/cache/opencode',
-  PACKAGE_NAME: 'oh-my-opencode-slim',
+// Mock logger to avoid noise
+mock.module('../../utils/logger', () => ({
+  log: mock(() => {}),
 }));
 
 mock.module('./checker', () => ({
@@ -17,14 +17,15 @@ mock.module('./cache', () => ({
   invalidatePackage: mock(() => false),
 }));
 
-mock.module('../../utils/logger', () => ({
-  log: mock(() => {}),
-}));
-
-import { getAutoUpdateInstallDir } from './index';
+// Cache buster for dynamic imports
+let importCounter = 0;
 
 describe('auto-update-checker/index', () => {
-  test('uses OpenCode cache dir for auto-update installs', () => {
-    expect(getAutoUpdateInstallDir()).toBe('/mock/cache/opencode');
+  test('uses OpenCode cache dir for auto-update installs', async () => {
+    const { getAutoUpdateInstallDir } = await import(
+      `./index?test=${importCounter++}`
+    );
+    // The actual cache dir depends on the platform, but it should be a string
+    expect(typeof getAutoUpdateInstallDir()).toBe('string');
   });
 });

src/hooks/auto-update-checker/index.ts

@@ -1,7 +1,6 @@
 import type { PluginInput } from '@opencode-ai/plugin';
 import { log } from '../../utils/logger';
 import { invalidatePackage } from './cache';
-import { CACHE_DIR, PACKAGE_NAME } from './constants';
 import {
   extractChannel,
   findPluginEntry,
@@ -9,6 +8,7 @@ import {
   getLatestVersion,
   getLocalDevVersion,
 } from './checker';
+import { CACHE_DIR, PACKAGE_NAME } from './constants';
 import type { AutoUpdateCheckerOptions } from './types';
 
 /**

src/hooks/todo-continuation/index.test.ts

@@ -52,11 +52,15 @@ describe('createTodoContinuationHook', () => {
     ).length;
   }
   function contCall(m: ReturnType<typeof mock>): any[] {
-    return m.mock.calls.find((c: any[]) =>
+    const call = m.mock.calls.find((c: any[]) =>
       (c[0]?.body?.parts as any[])?.some((p: any) =>
         p.text?.includes(SLIM_INTERNAL_INITIATOR_MARKER),
       ),
-    )!;
+    );
+    if (!call) {
+      throw new Error('No continuation call found');
+    }
+    return call;
   }
 
   describe('tool toggle', () => {

src/index.ts

@@ -15,6 +15,7 @@ import {
   createTodoContinuationHook,
   ForegroundFallbackManager,
 } from './hooks';
+import { createInterviewManager } from './interview';
 import { createBuiltinMcps } from './mcp';
 import { getMultiplexer, startAvailabilityCheck } from './multiplexer';
 import {
@@ -174,6 +175,7 @@ const OhMyOpenCodeLite: Plugin = async (ctx) => {
     autoEnable: config.todoContinuation?.autoEnable ?? false,
     autoEnableThreshold: config.todoContinuation?.autoEnableThreshold ?? 4,
   });
+  const interviewManager = createInterviewManager(ctx, config);
 
   return {
     name: 'oh-my-opencode-slim',
@@ -384,6 +386,8 @@ const OhMyOpenCodeLite: Plugin = async (ctx) => {
             'Enable auto-continuation — orchestrator keeps working through incomplete todos',
         };
       }
+
+      interviewManager.registerCommand(opencodeConfig);
     },
 
     event: async (input) => {
@@ -437,6 +441,12 @@ const OhMyOpenCodeLite: Plugin = async (ctx) => {
           properties?: { sessionID?: string };
         },
       );
+
+      await interviewManager.handleEvent(
+        input as {
+          event: { type: string; properties?: Record<string, unknown> };
+        },
+      );
     },
 
     // Direct interception of /auto-continue command — bypasses LLM round-trip
@@ -449,6 +459,15 @@ const OhMyOpenCodeLite: Plugin = async (ctx) => {
         },
         output as { parts: Array<{ type: string; text?: string }> },
       );
+
+      await interviewManager.handleCommandExecuteBefore(
+        input as {
+          command: string;
+          sessionID: string;
+          arguments: string;
+        },
+        output as { parts: Array<{ type: string; text?: string }> },
+      );
     },
 
     'chat.headers': chatHeadersHook['chat.headers'],

src/interview/index.ts

@@ -0,0 +1 @@
+export { createInterviewManager } from './manager';

src/interview/manager.ts

@@ -0,0 +1,53 @@
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { PluginConfig } from '../config';
+import { createInterviewServer } from './server';
+import { createInterviewService } from './service';
+
+/**
+ * Interview Manager - Composition root wiring the lean service ↔ server flow.
+ *
+ * Architecture:
+ * - Service: in-memory interview runtime + markdown document updates
+ * - Server: localhost UI + JSON API
+ * - Manager: small adapter exposing plugin hooks
+ *
+ * Dependency injection pattern:
+ * - Server depends on service.getState and service.submitAnswers
+ * - Service depends on server.ensureStarted (via setBaseUrlResolver)
+ * - Circular dependency resolved by lazy resolution
+ *
+ * Plugin integration:
+ * - registerCommand: injects /interview into OpenCode config
+ * - handleCommandExecuteBefore: intercepts /interview execution
+ * - handleEvent: listens to session.status and session.deleted events
+ */
+export function createInterviewManager(
+  ctx: PluginInput,
+  config: PluginConfig,
+): {
+  registerCommand: (config: Record<string, unknown>) => void;
+  handleCommandExecuteBefore: (
+    input: { command: string; sessionID: string; arguments: string },
+    output: { parts: Array<{ type: string; text?: string }> },
+  ) => Promise<void>;
+  handleEvent: (input: {
+    event: { type: string; properties?: Record<string, unknown> };
+  }) => Promise<void>;
+} {
+  const service = createInterviewService(ctx, config.interview);
+  const server = createInterviewServer({
+    getState: async (interviewId) => service.getInterviewState(interviewId),
+    submitAnswers: async (interviewId, answers) =>
+      service.submitAnswers(interviewId, answers),
+  });
+
+  // Inject server URL resolver into service (lazy: server starts on first request)
+  service.setBaseUrlResolver(() => server.ensureStarted());
+
+  return {
+    registerCommand: (config) => service.registerCommand(config),
+    handleCommandExecuteBefore: async (input, output) =>
+      service.handleCommandExecuteBefore(input, output),
+    handleEvent: async (input) => service.handleEvent(input),
+  };
+}

src/interview/parser.ts

@@ -0,0 +1,143 @@
+import type {
+  InterviewAssistantState,
+  InterviewMessage,
+  InterviewQuestion,
+} from './types';
+
+const INTERVIEW_BLOCK_REGEX =
+  /<interview_state>\s*([\s\S]*?)\s*<\/interview_state>/i;
+
+function normalizeQuestion(
+  value: Record<string, unknown>,
+  index: number,
+): InterviewQuestion | null {
+  const question =
+    typeof value.question === 'string' ? value.question.trim() : '';
+  if (!question) {
+    return null;
+  }
+
+  const options = Array.isArray(value.options)
+    ? value.options
+        .filter((option): option is string => typeof option === 'string')
+        .map((option) => option.trim())
+        .filter(Boolean)
+        .slice(0, 4)
+    : [];
+
+  return {
+    id:
+      typeof value.id === 'string' && value.id.trim().length > 0
+        ? value.id.trim()
+        : `q-${index + 1}`,
+    question,
+    options,
+    suggested:
+      typeof value.suggested === 'string' && value.suggested.trim().length > 0
+        ? value.suggested.trim()
+        : undefined,
+  };
+}
+
+export function flattenMessage(message: InterviewMessage): string {
+  return (message.parts ?? [])
+    .map((part) => part.text ?? '')
+    .join('\n')
+    .trim();
+}
+
+export function buildFallbackState(
+  messages: InterviewMessage[],
+): InterviewAssistantState {
+  const answerCount = messages.filter(
+    (message) => message.info?.role === 'user',
+  ).length;
+
+  return {
+    summary:
+      answerCount > 0
+        ? 'Interview in progress.'
+        : 'Waiting for the first interview response.',
+    questions: [],
+  };
+}
+
+export function parseAssistantState(
+  text: string,
+  maxQuestions = 2,
+): {
+  state: InterviewAssistantState | null;
+  error?: string;
+} {
+  const match = text.match(INTERVIEW_BLOCK_REGEX);
+  if (!match) {
+    return { state: null };
+  }
+
+  try {
+    const parsed = JSON.parse(match[1]) as Record<string, unknown>;
+    const summary =
+      typeof parsed.summary === 'string' ? parsed.summary.trim() : '';
+    const title =
+      typeof parsed.title === 'string' && parsed.title.trim().length > 0
+        ? parsed.title.trim()
+        : undefined;
+    const questions = Array.isArray(parsed.questions)
+      ? parsed.questions
+          .filter(
+            (value): value is Record<string, unknown> =>
+              typeof value === 'object' && value !== null,
+          )
+          .map((value, index) => normalizeQuestion(value, index))
+          .filter((value): value is InterviewQuestion => value !== null)
+          .slice(0, maxQuestions)
+      : [];
+
+    return {
+      state: {
+        summary,
+        title,
+        questions,
+      },
+    };
+  } catch (error) {
+    return {
+      state: null,
+      error:
+        error instanceof Error
+          ? error.message
+          : 'Failed to parse interview state',
+    };
+  }
+}
+
+export function findLatestAssistantState(
+  messages: InterviewMessage[],
+  maxQuestions = 2,
+): {
+  state: InterviewAssistantState | null;
+  latestAssistantError?: string;
+} {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    const message = messages[index];
+    if (message.info?.role !== 'assistant') {
+      continue;
+    }
+
+    const parsed = parseAssistantState(flattenMessage(message), maxQuestions);
+    if (parsed.state) {
+      return {
+        state: parsed.state,
+      };
+    }
+
+    return {
+      state: null,
+      latestAssistantError: parsed.error ?? 'Missing <interview_state> block',
+    };
+  }
+
+  return {
+    state: null,
+  };
+}

src/interview/prompts.ts

@@ -0,0 +1,90 @@
+import type { InterviewQuestion } from './types';
+
+function formatQuestionContext(questions: InterviewQuestion[]): string {
+  if (questions.length === 0) {
+    return 'No current interview questions were parsed.';
+  }
+
+  return questions
+    .map((question, index) => {
+      const options = question.options.length
+        ? `Options: ${question.options.join(' | ')}`
+        : 'Options: freeform';
+      const suggested = question.suggested
+        ? `Suggested: ${question.suggested}`
+        : 'Suggested: none';
+      return `${index + 1}. ${question.question}\n${options}\n${suggested}`;
+    })
+    .join('\n\n');
+}
+
+export function buildKickoffPrompt(idea: string, maxQuestions: number): string {
+  return [
+    'You are running an interview q&a session for the user inside their repository.',
+    `Initial idea: ${idea}`,
+    `Clarify the idea through short rounds of at most ${maxQuestions} questions at a time.`,
+    'When useful, each question may include 2 to 4 answer options and one suggested option.',
+    'Be practical. Focus on the highest-ambiguity and highest-risk decisions first.',
+    'After any short human-friendly preface, you MUST include a machine-readable block in this exact format:',
+    '<interview_state>',
+    '{',
+    '  "summary": "one short paragraph about the current understanding",',
+    '  "title": "concise-kebab-case-title-for-filename",',
+    '  "questions": [',
+    '    {',
+    '      "id": "short-kebab-id-2",',
+    '      "question": "question text",',
+    '      "options": ["option 1", "option 2", "option 3"],',
+    '      "suggested": "best suggested option"',
+    '    }',
+    '  ]',
+    '}',
+    '</interview_state>',
+    'Rules:',
+    `- Return 0 to ${maxQuestions} questions.`,
+    '- If there are no more useful questions, return zero questions.',
+    `- Do not ask more than ${maxQuestions} questions in one round.`,
+    '- Provide a concise "title" field (kebab-case, 3-6 words) suitable for a filename.',
+  ].join('\n');
+}
+
+export function buildResumePrompt(
+  document: string,
+  maxQuestions: number,
+): string {
+  return [
+    'Resume the interview from this existing markdown document.',
+    'Use the current spec and Q&A history as ground truth so far.',
+    'Do not restart from scratch.',
+    '',
+    document,
+    '',
+    `Ask the next highest-value clarifying questions, up to ${maxQuestions} at a time.`,
+    'If there are no more useful questions, return zero questions.',
+    'Return the same <interview_state> JSON block format as before.',
+  ].join('\n');
+}
+
+export function buildAnswerPrompt(
+  answers: Array<{ questionId: string; answer: string }>,
+  questions: InterviewQuestion[],
+  maxQuestions: number,
+): string {
+  const answerText = answers
+    .map(
+      (answer, index) =>
+        `${index + 1}. ${answer.questionId}: ${answer.answer.trim()}`,
+    )
+    .join('\n');
+
+  return [
+    'Continue the same interview.',
+    'These were the active questions:',
+    formatQuestionContext(questions),
+    'The user answered:',
+    answerText,
+    'Now update your understanding and ask the next highest-value clarifying questions.',
+    `Return 0 to ${maxQuestions} questions. If there are no more useful questions, return zero questions.`,
+    'Return the same <interview_state> JSON block format as before.',
+  ].join('\n\n');
+}

src/interview/server.ts

@@ -0,0 +1,208 @@
+import {
+  createServer,
+  type IncomingMessage,
+  type ServerResponse,
+} from 'node:http';
+import { URL } from 'node:url';
+import type { InterviewAnswer, InterviewState } from './types';
+import { renderInterviewPage } from './ui';
+
+function getSubmissionStatus(error: unknown): number {
+  if (error instanceof SyntaxError) {
+    return 400;
+  }
+
+  const message = error instanceof Error ? error.message : '';
+  if (message === 'Interview not found') {
+    return 404;
+  }
+  if (message.includes('busy')) {
+    return 409;
+  }
+  if (
+    message.includes('waiting for a valid agent update') ||
+    message.includes('There are no active interview questions') ||
+    message.includes('Answer every active interview question') ||
+    message.includes('Answers do not match') ||
+    message.includes('Request body too large') ||
+    message.includes('Invalid answers payload') ||
+    message.includes('no longer active')
+  ) {
+    return 400;
+  }
+
+  return 500;
+}
+
+function parseAnswersPayload(value: unknown): { answers: InterviewAnswer[] } {
+  if (!value || typeof value !== 'object') {
+    throw new Error('Invalid answers payload.');
+  }
+  const answersRaw = (value as { answers?: unknown }).answers;
+  if (!Array.isArray(answersRaw)) {
+    throw new Error('Invalid answers payload.');
+  }
+
+  return {
+    answers: answersRaw.map((answer) => {
+      if (!answer || typeof answer !== 'object') {
+        throw new Error('Invalid answers payload.');
+      }
+      const record = answer as { questionId?: unknown; answer?: unknown };
+      if (
+        typeof record.questionId !== 'string' ||
+        typeof record.answer !== 'string'
+      ) {
+        throw new Error('Invalid answers payload.');
+      }
+      return {
+        questionId: record.questionId.trim(),
+        answer: record.answer.trim(),
+      };
+    }),
+  };
+}
+
+async function readJsonBody(request: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > 64 * 1024) {
+      throw new Error('Request body too large');
+    }
+    chunks.push(buffer);
+  }
+
+  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  return raw ? JSON.parse(raw) : {};
+}
+
+function sendJson(
+  response: ServerResponse,
+  status: number,
+  value: unknown,
+): void {
+  response.statusCode = status;
+  response.setHeader('content-type', 'application/json; charset=utf-8');
+  response.end(`${JSON.stringify(value)}\n`);
+}
+
+function sendHtml(response: ServerResponse, html: string): void {
+  response.statusCode = 200;
+  response.setHeader('content-type', 'text/html; charset=utf-8');
+  response.end(html);
+}
+
+export function createInterviewServer(deps: {
+  getState: (interviewId: string) => Promise<InterviewState>;
+  submitAnswers: (
+    interviewId: string,
+    answers: InterviewAnswer[],
+  ) => Promise<void>;
+}): {
+  ensureStarted: () => Promise<string>;
+} {
+  let baseUrl: string | null = null;
+  let startPromise: Promise<string> | null = null;
+
+  async function handle(
+    request: IncomingMessage,
+    response: ServerResponse,
+  ): Promise<void> {
+    const url = new URL(request.url ?? '/', 'http://127.0.0.1');
+    const pathname = url.pathname;
+
+    if (request.method === 'GET' && pathname.startsWith('/interview/')) {
+      sendHtml(
+        response,
+        renderInterviewPage(pathname.split('/').pop() ?? 'unknown'),
+      );
+      return;
+    }
+
+    const stateMatch = pathname.match(/^\/api\/interviews\/([^/]+)\/state$/);
+    if (request.method === 'GET' && stateMatch) {
+      try {
+        const state = await deps.getState(stateMatch[1]);
+        sendJson(response, 200, state);
+      } catch (error) {
+        sendJson(response, 404, {
+          error: error instanceof Error ? error.message : 'Interview not found',
+        });
+      }
+      return;
+    }
+
+    const answersMatch = pathname.match(
+      /^\/api\/interviews\/([^/]+)\/answers$/,
+    );
+    if (request.method === 'POST' && answersMatch) {
+      try {
+        const body = parseAnswersPayload(await readJsonBody(request));
+        await deps.submitAnswers(answersMatch[1], body.answers);
+        sendJson(response, 200, {
+          ok: true,
+          message: 'Answers submitted to the OpenCode session.',
+        });
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : 'Failed to submit answers.';
+        const status = getSubmissionStatus(error);
+        sendJson(response, status, {
+          ok: false,
+          message,
+        });
+      }
+      return;
+    }
+
+    sendJson(response, 404, { error: 'Not found' });
+  }
+
+  async function ensureStarted(): Promise<string> {
+    if (baseUrl) {
+      return baseUrl;
+    }
+
+    if (startPromise) {
+      return startPromise;
+    }
+
+    startPromise = new Promise((resolve, reject) => {
+      const server = createServer((request, response) => {
+        handle(request, response).catch((error) => {
+          sendJson(response, 500, {
+            error:
+              error instanceof Error ? error.message : 'Internal server error',
+          });
+        });
+      });
+
+      server.on('error', (error) => {
+        startPromise = null;
+        reject(error);
+      });
+
+      server.listen(0, '127.0.0.1', () => {
+        const address = server.address();
+        if (!address || typeof address === 'string') {
+          startPromise = null;
+          reject(new Error('Failed to start interview server'));
+          return;
+        }
+
+        baseUrl = `http://127.0.0.1:${address.port}`;
+        resolve(baseUrl);
+      });
+    });
+
+    return startPromise;
+  }
+
+  return {
+    ensureStarted,
+  };
+}

src/interview/service.ts

@@ -0,0 +1,705 @@
+import { spawn } from 'node:child_process';
+import * as fsSync from 'node:fs';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { PluginInput } from '@opencode-ai/plugin';
+import type { InterviewConfig } from '../config';
+import {
+  createInternalAgentTextPart,
+  hasInternalInitiatorMarker,
+  log,
+} from '../utils';
+import { buildFallbackState, findLatestAssistantState } from './parser';
+import {
+  buildAnswerPrompt,
+  buildKickoffPrompt,
+  buildResumePrompt,
+} from './prompts';
+import type {
+  InterviewAnswer,
+  InterviewMessage,
+  InterviewQuestion,
+  InterviewRecord,
+  InterviewState,
+} from './types';
+
+const COMMAND_NAME = 'interview';
+const DEFAULT_MAX_QUESTIONS = 2;
+const DEFAULT_OUTPUT_FOLDER = 'interview';
+const DEFAULT_AUTO_OPEN_BROWSER = true;
+
+function slugify(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48);
+}
+
+/**
+ * Open a URL in the default browser.
+ * Supports macOS, Linux, and Windows. Failures are logged but not thrown.
+ */
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  let command: string;
+  let args: string[];
+
+  if (platform === 'darwin') {
+    command = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    command = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    // Linux and other Unix-like systems
+    command = 'xdg-open';
+    args = [url];
+  }
+
+  try {
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.on('error', (error) => {
+      log('[interview] failed to open browser:', { error: error.message, url });
+    });
+    child.unref();
+  } catch (error) {
+    log('[interview] failed to spawn browser opener:', {
+      error: error instanceof Error ? error.message : String(error),
+      url,
+    });
+  }
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function normalizeOutputFolder(outputFolder: string): string {
+  const normalized = outputFolder.trim().replace(/^\/+|\/+$/g, '');
+  return normalized || DEFAULT_OUTPUT_FOLDER;
+}
+
+function createInterviewDirectoryPath(
+  directory: string,
+  outputFolder: string,
+): string {
+  return path.join(directory, normalizeOutputFolder(outputFolder));
+}
+
+function createInterviewFilePath(
+  directory: string,
+  outputFolder: string,
+  idea: string,
+): string {
+  const fileName = `${slugify(idea) || 'interview'}.md`;
+  return path.join(
+    createInterviewDirectoryPath(directory, outputFolder),
+    fileName,
+  );
+}
+
+function relativeInterviewPath(directory: string, filePath: string): string {
+  return path.relative(directory, filePath) || path.basename(filePath);
+}
+
+function extractHistorySection(document: string): string {
+  const marker = '## Q&A history\n\n';
+  const index = document.indexOf(marker);
+  return index >= 0 ? document.slice(index + marker.length).trim() : '';
+}
+
+function extractSummarySection(document: string): string {
+  const marker = '## Current spec\n\n';
+  const historyMarker = '\n\n## Q&A history';
+  const start = document.indexOf(marker);
+  if (start < 0) {
+    return '';
+  }
+  const summaryStart = start + marker.length;
+  const summaryEnd = document.indexOf(historyMarker, summaryStart);
+  return document
+    .slice(summaryStart, summaryEnd >= 0 ? summaryEnd : undefined)
+    .trim();
+}
+
+function extractTitle(document: string): string {
+  const match = document.match(/^#\s+(.+)$/m);
+  return match?.[1]?.trim() ?? '';
+}
+
+function buildInterviewDocument(
+  idea: string,
+  summary: string,
+  history: string,
+): string {
+  const normalizedSummary = summary.trim() || 'Waiting for interview answers.';
+  const normalizedHistory = history.trim() || 'No answers yet.';
+
+  return [
+    `# ${idea}`,
+    '',
+    '## Current spec',
+    '',
+    normalizedSummary,
+    '',
+    '## Q&A history',
+    '',
+    normalizedHistory,
+    '',
+  ].join('\n');
+}
+
+async function ensureInterviewFile(record: InterviewRecord): Promise<void> {
+  await fs.mkdir(path.dirname(record.markdownPath), { recursive: true });
+  try {
+    await fs.access(record.markdownPath);
+  } catch {
+    await fs.writeFile(
+      record.markdownPath,
+      buildInterviewDocument(record.idea, '', ''),
+      'utf8',
+    );
+  }
+}
+
+async function readInterviewDocument(record: InterviewRecord): Promise<string> {
+  await ensureInterviewFile(record);
+  return fs.readFile(record.markdownPath, 'utf8');
+}
+
+async function rewriteInterviewDocument(
+  record: InterviewRecord,
+  summary: string,
+): Promise<string> {
+  const existing = await readInterviewDocument(record);
+  const history = extractHistorySection(existing);
+  const next = buildInterviewDocument(record.idea, summary, history);
+  await fs.writeFile(record.markdownPath, next, 'utf8');
+  return next;
+}
+
+async function appendInterviewAnswers(
+  record: InterviewRecord,
+  questions: InterviewQuestion[],
+  answers: InterviewAnswer[],
+): Promise<void> {
+  const existing = await readInterviewDocument(record);
+  const summary = extractSummarySection(existing);
+  const history = extractHistorySection(existing);
+  const questionMap = new Map(
+    questions.map((question) => [question.id, question]),
+  );
+  const appended = answers
+    .map((answer) => {
+      const question = questionMap.get(answer.questionId);
+      return question
+        ? `Q: ${question.question}\nA: ${answer.answer.trim()}`
+        : null;
+    })
+    .filter((value): value is string => value !== null)
+    .join('\n\n');
+  const nextHistory = [history === 'No answers yet.' ? '' : history, appended]
+    .filter(Boolean)
+    .join('\n\n');
+  await fs.writeFile(
+    record.markdownPath,
+    buildInterviewDocument(record.idea, summary, nextHistory),
+    'utf8',
+  );
+}
+
+function resolveExistingInterviewPath(
+  directory: string,
+  outputFolder: string,
+  value: string,
+): string | null {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  const outputDir = createInterviewDirectoryPath(directory, outputFolder);
+  const candidates = new Set<string>();
+
+  if (path.isAbsolute(trimmed)) {
+    candidates.add(trimmed);
+  } else {
+    candidates.add(path.resolve(directory, trimmed));
+    candidates.add(path.join(outputDir, trimmed));
+    if (!trimmed.endsWith('.md')) {
+      candidates.add(path.join(outputDir, `${trimmed}.md`));
+    }
+  }
+
+  for (const candidate of candidates) {
+    if (path.extname(candidate) !== '.md') {
+      continue;
+    }
+    if (fsSync.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+export function createInterviewService(
+  ctx: PluginInput,
+  config?: InterviewConfig,
+  deps?: {
+    openBrowser?: (url: string) => void;
+  },
+): {
+  setBaseUrlResolver: (resolver: () => Promise<string>) => void;
+  registerCommand: (config: Record<string, unknown>) => void;
+  handleCommandExecuteBefore: (
+    input: { command: string; sessionID: string; arguments: string },
+    output: { parts: Array<{ type: string; text?: string }> },
+  ) => Promise<void>;
+  handleEvent: (input: {
+    event: { type: string; properties?: Record<string, unknown> };
+  }) => Promise<void>;
+  getInterviewState: (interviewId: string) => Promise<InterviewState>;
+  submitAnswers: (
+    interviewId: string,
+    answers: InterviewAnswer[],
+  ) => Promise<void>;
+} {
+  const maxQuestions = config?.maxQuestions ?? DEFAULT_MAX_QUESTIONS;
+  const outputFolder = normalizeOutputFolder(
+    config?.outputFolder ?? DEFAULT_OUTPUT_FOLDER,
+  );
+  const autoOpenBrowser = config?.autoOpenBrowser ?? DEFAULT_AUTO_OPEN_BROWSER;
+  const browserOpener = deps?.openBrowser ?? openBrowser;
+  const activeInterviewIds = new Map<string, string>();
+  const interviewsById = new Map<string, InterviewRecord>();
+  const sessionBusy = new Map<string, boolean>();
+  const browserOpened = new Set<string>(); // Track interviews that have opened browser
+  let resolveBaseUrl: (() => Promise<string>) | null = null;
+
+  function setBaseUrlResolver(resolver: () => Promise<string>): void {
+    resolveBaseUrl = resolver;
+  }
+
+  async function ensureServer(): Promise<string> {
+    if (!resolveBaseUrl) {
+      throw new Error('Interview server is not attached');
+    }
+    return resolveBaseUrl();
+  }
+
+  function maybeOpenBrowser(interviewId: string, url: string): void {
+    if (!autoOpenBrowser) {
+      return;
+    }
+    if (browserOpened.has(interviewId)) {
+      return;
+    }
+    browserOpened.add(interviewId);
+    browserOpener(url);
+  }
+
+  async function maybeRenameWithTitle(
+    interview: InterviewRecord,
+    assistantTitle: string | undefined,
+  ): Promise<void> {
+    if (!assistantTitle) {
+      return;
+    }
+    const newSlug = slugify(assistantTitle);
+    if (!newSlug) {
+      return;
+    }
+
+    const currentFileName = path.basename(interview.markdownPath, '.md');
+    // If already matches (or user-provided idea matches), skip
+    if (currentFileName === newSlug) {
+      return;
+    }
+
+    const dir = path.dirname(interview.markdownPath);
+    const newPath = path.join(dir, `${newSlug}.md`);
+
+    // Don't overwrite existing files
+    try {
+      await fs.access(newPath);
+      // File exists, don't rename
+      return;
+    } catch {
+      // File doesn't exist, safe to rename
+    }
+
+    try {
+      await fs.rename(interview.markdownPath, newPath);
+      interview.markdownPath = newPath;
+      log('[interview] renamed file with assistant title:', {
+        from: currentFileName,
+        to: newSlug,
+      });
+    } catch (error) {
+      log('[interview] failed to rename file:', {
+        error: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
+  async function loadMessages(sessionID: string): Promise<InterviewMessage[]> {
+    const result = await ctx.client.session.messages({
+      path: { id: sessionID },
+    });
+    return result.data as InterviewMessage[];
+  }
+
+  function isUserVisibleMessage(message: InterviewMessage): boolean {
+    return !(message.parts ?? []).some((part) =>
+      hasInternalInitiatorMarker(part),
+    );
+  }
+
+  function getInterviewById(interviewId: string): InterviewRecord | null {
+    return interviewsById.get(interviewId) ?? null;
+  }
+
+  async function createInterview(
+    sessionID: string,
+    idea: string,
+  ): Promise<InterviewRecord> {
+    const normalizedIdea = idea.trim();
+    const activeId = activeInterviewIds.get(sessionID);
+    if (activeId) {
+      const active = interviewsById.get(activeId);
+      if (active && active.status === 'active') {
+        if (active.idea === normalizedIdea) {
+          return active;
+        }
+
+        active.status = 'abandoned';
+      }
+    }
+
+    const messages = await loadMessages(sessionID);
+    const record: InterviewRecord = {
+      id: `${Date.now()}-${slugify(idea) || 'interview'}`,
+      sessionID,
+      idea: normalizedIdea,
+      markdownPath: createInterviewFilePath(ctx.directory, outputFolder, idea),
+      createdAt: nowIso(),
+      status: 'active',
+      baseMessageCount: messages.length,
+    };
+
+    await ensureInterviewFile(record);
+    activeInterviewIds.set(sessionID, record.id);
+    interviewsById.set(record.id, record);
+    return record;
+  }
+
+  async function resumeInterview(
+    sessionID: string,
+    markdownPath: string,
+  ): Promise<InterviewRecord> {
+    const activeId = activeInterviewIds.get(sessionID);
+    if (activeId) {
+      const active = interviewsById.get(activeId);
+      if (active && active.status === 'active') {
+        if (active.markdownPath === markdownPath) {
+          return active;
+        }
+
+        active.status = 'abandoned';
+      }
+    }
+
+    const document = await fs.readFile(markdownPath, 'utf8');
+    const messages = await loadMessages(sessionID);
+    const title = extractTitle(document);
+    const record: InterviewRecord = {
+      id: `${Date.now()}-${slugify(path.basename(markdownPath, '.md')) || 'interview'}`,
+      sessionID,
+      idea: title || path.basename(markdownPath, '.md'),
+      markdownPath,
+      createdAt: nowIso(),
+      status: 'active',
+      baseMessageCount: messages.length,
+    };
+
+    activeInterviewIds.set(sessionID, record.id);
+    interviewsById.set(record.id, record);
+    return record;
+  }
+
+  async function syncInterview(
+    interview: InterviewRecord,
+  ): Promise<InterviewState> {
+    const allMessages = await loadMessages(interview.sessionID);
+    const interviewMessages = allMessages
+      .slice(interview.baseMessageCount)
+      .filter(isUserVisibleMessage);
+    const parsed = findLatestAssistantState(interviewMessages, maxQuestions);
+    const existingDocument = await readInterviewDocument(interview);
+    const fallbackState = buildFallbackState(interviewMessages);
+    const state = parsed.state ?? {
+      ...fallbackState,
+      summary: extractSummarySection(existingDocument) || fallbackState.summary,
+    };
+
+    // Rename file if assistant provided a title (and file hasn't been renamed yet)
+    await maybeRenameWithTitle(interview, state.title);
+
+    const document = await rewriteInterviewDocument(interview, state.summary);
+
+    return {
+      interview,
+      url: `${await ensureServer()}/interview/${interview.id}`,
+      markdownPath: relativeInterviewPath(
+        ctx.directory,
+        interview.markdownPath,
+      ),
+      mode:
+        interview.status === 'abandoned'
+          ? 'abandoned'
+          : parsed.latestAssistantError
+            ? 'error'
+            : sessionBusy.get(interview.sessionID) === true
+              ? 'awaiting-agent'
+              : state.questions.length > 0
+                ? 'awaiting-user'
+                : 'awaiting-agent',
+      lastParseError: parsed.latestAssistantError,
+      isBusy: sessionBusy.get(interview.sessionID) === true,
+      summary: state.summary,
+      questions: state.questions,
+      document,
+    };
+  }
+
+  async function notifyInterviewUrl(
+    sessionID: string,
+    interview: InterviewRecord,
+  ): Promise<void> {
+    const baseUrl = await ensureServer();
+    const url = `${baseUrl}/interview/${interview.id}`;
+
+    // Auto-open browser on initial creation (not on every poll/refresh)
+    maybeOpenBrowser(interview.id, url);
+
+    await ctx.client.session.prompt({
+      path: { id: sessionID },
+      body: {
+        noReply: true,
+        parts: [
+          {
+            type: 'text',
+            text: [
+              '⎔ Interview UI ready',
+              '',
+              `Open: ${url}`,
+              `Document: ${relativeInterviewPath(ctx.directory, interview.markdownPath)}`,
+              '',
+              '[system status: continue without acknowledging this notification]',
+            ].join('\n'),
+          },
+        ],
+      },
+    });
+  }
+
+  function registerCommand(opencodeConfig: Record<string, unknown>): void {
+    const configCommand = opencodeConfig.command as
+      | Record<string, unknown>
+      | undefined;
+    if (!configCommand?.[COMMAND_NAME]) {
+      if (!opencodeConfig.command) {
+        opencodeConfig.command = {};
+      }
+      (opencodeConfig.command as Record<string, unknown>)[COMMAND_NAME] = {
+        template: 'Start an interview and write a live markdown spec',
+        description:
+          'Open a localhost interview UI linked to the current OpenCode session',
+      };
+    }
+  }
+
+  async function getInterviewState(
+    interviewId: string,
+  ): Promise<InterviewState> {
+    const interview = getInterviewById(interviewId);
+    if (!interview) {
+      throw new Error('Interview not found');
+    }
+    return syncInterview(interview);
+  }
+
+  async function submitAnswers(
+    interviewId: string,
+    answers: InterviewAnswer[],
+  ): Promise<void> {
+    const interview = getInterviewById(interviewId);
+    if (!interview) {
+      throw new Error('Interview not found');
+    }
+    if (interview.status === 'abandoned') {
+      throw new Error('Interview session is no longer active.');
+    }
+    if (sessionBusy.get(interview.sessionID) === true) {
+      throw new Error(
+        'Interview session is busy. Wait for the current response.',
+      );
+    }
+
+    // Acquire busy lock immediately before any async operations to prevent race
+    sessionBusy.set(interview.sessionID, true);
+    let promptSent = false;
+
+    try {
+      const state = await getInterviewState(interviewId);
+      if (state.mode === 'error') {
+        throw new Error('Interview is waiting for a valid agent update.');
+      }
+
+      const activeQuestionIds = new Set(
+        state.questions.map((question) => question.id),
+      );
+      if (activeQuestionIds.size === 0) {
+        throw new Error('There are no active interview questions to answer.');
+      }
+      if (answers.length !== activeQuestionIds.size) {
+        throw new Error(
+          'Answer every active interview question before submitting.',
+        );
+      }
+      const invalidAnswer = answers.find(
+        (answer) =>
+          !activeQuestionIds.has(answer.questionId) || !answer.answer.trim(),
+      );
+      if (invalidAnswer) {
+        throw new Error(
+          'Answers do not match the current interview questions.',
+        );
+      }
+
+      await appendInterviewAnswers(interview, state.questions, answers);
+      const prompt = buildAnswerPrompt(answers, state.questions, maxQuestions);
+
+      await ctx.client.session.prompt({
+        path: { id: interview.sessionID },
+        body: {
+          parts: [createInternalAgentTextPart(prompt)],
+        },
+      });
+      promptSent = true;
+    } finally {
+      if (!promptSent) {
+        sessionBusy.set(interview.sessionID, false);
+      }
+    }
+  }
+
+  async function handleCommandExecuteBefore(
+    input: { command: string; sessionID: string; arguments: string },
+    output: { parts: Array<{ type: string; text?: string }> },
+  ): Promise<void> {
+    if (input.command !== COMMAND_NAME) {
+      return;
+    }
+
+    const idea = input.arguments.trim();
+    output.parts.length = 0;
+
+    if (!idea) {
+      const activeId = activeInterviewIds.get(input.sessionID);
+      const interview = activeId ? interviewsById.get(activeId) : null;
+      if (!interview || interview.status !== 'active') {
+        output.parts.push(
+          createInternalAgentTextPart(
+            'The user ran /interview without an idea. Ask them for the product idea in one sentence.',
+          ),
+        );
+        return;
+      }
+
+      await notifyInterviewUrl(input.sessionID, interview);
+      output.parts.push(
+        createInternalAgentTextPart(
+          `The interview UI was reopened for the current session. If your latest interview turn already contains unanswered questions, do not repeat them. Otherwise continue the interview with up to ${maxQuestions} clarifying questions and include the structured <interview_state> block.`,
+        ),
+      );
+      return;
+    }
+
+    const resumePath = resolveExistingInterviewPath(
+      ctx.directory,
+      outputFolder,
+      idea,
+    );
+    if (resumePath) {
+      const interview = await resumeInterview(input.sessionID, resumePath);
+      const document = await fs.readFile(interview.markdownPath, 'utf8');
+      await notifyInterviewUrl(input.sessionID, interview);
+      output.parts.push(
+        createInternalAgentTextPart(buildResumePrompt(document, maxQuestions)),
+      );
+      return;
+    }
+
+    const interview = await createInterview(input.sessionID, idea);
+    await notifyInterviewUrl(input.sessionID, interview);
+    output.parts.push(
+      createInternalAgentTextPart(buildKickoffPrompt(idea, maxQuestions)),
+    );
+  }
+
+  async function handleEvent(input: {
+    event: { type: string; properties?: Record<string, unknown> };
+  }): Promise<void> {
+    const { event } = input;
+    const properties = event.properties ?? {};
+
+    if (event.type === 'session.status') {
+      const sessionID = properties.sessionID as string | undefined;
+      const status = properties.status as { type?: string } | undefined;
+      if (sessionID) {
+        sessionBusy.set(sessionID, status?.type === 'busy');
+      }
+      return;
+    }
+
+    if (event.type === 'session.deleted') {
+      const deletedSessionId =
+        ((properties.info as { id?: string } | undefined)?.id ??
+          (properties.sessionID as string | undefined)) ||
+        null;
+      if (!deletedSessionId) {
+        return;
+      }
+
+      sessionBusy.delete(deletedSessionId);
+      const interviewId = activeInterviewIds.get(deletedSessionId);
+      if (!interviewId) {
+        return;
+      }
+
+      const interview = interviewsById.get(interviewId);
+      if (!interview) {
+        return;
+      }
+
+      interview.status = 'abandoned';
+      activeInterviewIds.delete(deletedSessionId);
+      log('[interview] session deleted, interview marked abandoned', {
+        sessionID: deletedSessionId,
+        interviewId,
+      });
+    }
+  }
+
+  return {
+    setBaseUrlResolver,
+    registerCommand,
+    handleCommandExecuteBefore,
+    handleEvent,
+    getInterviewState,
+    submitAnswers,
+  };
+}

src/interview/types.ts

@@ -0,0 +1,52 @@
+export interface InterviewQuestion {
+  id: string;
+  question: string;
+  options: string[];
+  suggested?: string;
+}
+
+export interface InterviewAnswer {
+  questionId: string;
+  answer: string;
+}
+
+export interface InterviewAssistantState {
+  summary: string;
+  title?: string;
+  questions: InterviewQuestion[];
+}
+
+export interface InterviewRecord {
+  id: string;
+  sessionID: string;
+  idea: string;
+  markdownPath: string;
+  createdAt: string;
+  status: 'active' | 'abandoned';
+  baseMessageCount: number;
+}
+
+export interface InterviewMessagePart {
+  type?: string;
+  text?: string;
+}
+
+export interface InterviewMessage {
+  info?: {
+    role?: string;
+    [key: string]: unknown;
+  };
+  parts?: InterviewMessagePart[];
+}
+
+export interface InterviewState {
+  interview: InterviewRecord;
+  url: string;
+  markdownPath: string;
+  mode: 'awaiting-agent' | 'awaiting-user' | 'abandoned' | 'error';
+  lastParseError?: string;
+  isBusy: boolean;
+  summary: string;
+  questions: InterviewQuestion[];
+  document: string;
+}

src/interview/ui.ts

@@ -0,0 +1,678 @@
+export function renderInterviewPage(interviewId: string): string {
+  const safeTitle = interviewId
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Interview ${safeTitle}</title>
+    <style>
+      :root { color-scheme: dark; }
+      body { 
+        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol"; 
+        margin: 0; 
+        background: #000000; 
+        color: #ffffff; 
+        line-height: 1.6;
+        -webkit-font-smoothing: antialiased;
+        font-size: 16px;
+      }
+      .wrap { max-width: 680px; margin: 0 auto; padding: 56px 24px; }
+      .brand-header {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 16px;
+        margin-bottom: 32px;
+        text-align: center;
+      }
+      .brand-mark {
+        width: 144px;
+        height: 144px;
+        object-fit: contain;
+        filter: drop-shadow(0 10px 30px rgba(255,255,255,0.1));
+      }
+      h1 { font-size: 32px; font-weight: 600; letter-spacing: -0.02em; margin-bottom: 12px; line-height: 1.2; }
+      h2 { font-size: 18px; font-weight: 500; letter-spacing: 0.05em; text-transform: uppercase; color: rgba(255,255,255,0.4); margin-bottom: 24px; border-bottom: 1px solid rgba(255,255,255,0.1); padding-bottom: 12px; }
+      h3 { font-size: 18px; font-weight: 500; margin-bottom: 16px; line-height: 1.4; }
+      p { margin-top: 0; }
+      .muted { color: rgba(255,255,255,0.5); font-size: 16px; }
+      .meta { display: flex; align-items: center; justify-content: space-between; font-size: 13px; color: rgba(255,255,255,0.4); margin-bottom: 16px; letter-spacing: 0.05em; text-transform: uppercase; }
+      
+      .file-path-container {
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+        font-size: 13px;
+        color: rgba(255,255,255,0.6);
+        background: rgba(255,255,255,0.05);
+        padding: 8px 12px;
+        border-radius: 6px;
+        margin-bottom: 36px;
+        display: flex;
+        align-items: center;
+        gap: 8px;
+        border: 1px solid rgba(255,255,255,0.08);
+      }
+      .file-path-icon {
+        opacity: 0.5;
+      }
+      
+      .question { 
+        background: rgba(255,255,255,0.02); 
+        border: 1px solid rgba(255,255,255,0.1); 
+        border-left: 1px solid rgba(255,255,255,0.1);
+        border-radius: 6px; 
+        padding: 28px; 
+        margin-bottom: 32px; 
+        transition: all 0.3s cubic-bezier(0.2, 0.8, 0.2, 1);
+      }
+      .question:focus-within {
+        border-color: rgba(255,255,255,0.3);
+      }
+      
+      /* Make active question much clearer */
+      .question.active-question {
+        background: rgba(255,255,255,0.04);
+        border-color: rgba(255,255,255,0.4);
+        border-left: 4px solid #ffffff;
+        box-shadow: 0 8px 32px rgba(0,0,0,0.4), 0 0 0 1px rgba(255,255,255,0.1);
+        transform: translateX(4px);
+      }
+      
+      .options { display: flex; flex-direction: column; gap: 10px; margin-bottom: 20px; }
+      
+      .option { 
+        border: 1px solid rgba(255,255,255,0.1); 
+        background: transparent; 
+        color: inherit; 
+        border-radius: 6px; 
+        padding: 14px 18px; 
+        cursor: pointer; 
+        text-align: left;
+        font-size: 16px;
+        transition: all 0.2s ease;
+        display: flex;
+        align-items: center;
+      }
+      .option:hover {
+        background: rgba(255,255,255,0.06);
+        border-color: rgba(255,255,255,0.3);
+      }
+      .option.selected { 
+        background: #ffffff; 
+        color: #000000; 
+        border-color: #ffffff; 
+        font-weight: 500;
+      }
+      
+      .shortcut {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        background: rgba(255,255,255,0.1);
+        color: rgba(255,255,255,0.8);
+        border-radius: 4px;
+        min-width: 20px;
+        height: 20px;
+        padding: 0 4px;
+        font-size: 12px;
+        margin-right: 12px;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      }
+      .option.selected .shortcut {
+        background: rgba(0,0,0,0.15);
+        color: rgba(0,0,0,0.9);
+      }
+       
+      .option-text {
+        flex: 1;
+        line-height: 1.4;
+      }
+
+      .recommended-badge {
+        font-size: 11px;
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+        background: rgba(255,255,255,0.15);
+        color: rgba(255,255,255,0.9);
+        padding: 4px 8px;
+        border-radius: 999px;
+        margin-left: 12px;
+        font-weight: 600;
+      }
+      .option.selected .recommended-badge {
+        background: rgba(0,0,0,0.15);
+        color: rgba(0,0,0,0.8);
+      }
+
+      .submit-shortcut {
+        display: inline-block;
+        margin-left: 10px;
+        padding: 3px 8px;
+        border-radius: 999px;
+        background: rgba(0,0,0,0.08);
+        color: rgba(0,0,0,0.7);
+        font-size: 12px;
+        font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      }
+      
+      textarea { 
+        width: 100%; 
+        box-sizing: border-box;
+        min-height: 140px; 
+        border-radius: 6px; 
+        border: 1px solid rgba(255,255,255,0.15); 
+        background: rgba(0,0,0,0.6); 
+        color: inherit; 
+        padding: 16px; 
+        font-family: inherit;
+        font-size: 16px;
+        line-height: 1.5;
+        resize: vertical;
+        outline: none;
+        transition: border-color 0.2s ease;
+      }
+      textarea:focus {
+        border-color: rgba(255,255,255,0.5);
+        box-shadow: 0 0 0 1px rgba(255,255,255,0.1);
+      }
+
+      .hidden-textarea {
+        display: none;
+      }
+      
+      button.primary { 
+        background: #ffffff; 
+        color: #000000; 
+        border: 0; 
+        border-radius: 6px; 
+        padding: 16px 24px; 
+        font-size: 16px;
+        font-weight: 600;
+        cursor: pointer; 
+        width: 100%;
+        transition: opacity 0.2s ease, transform 0.1s ease;
+      }
+      button.primary:hover:not(:disabled) {
+        opacity: 0.9;
+        transform: translateY(-1px);
+      }
+      button.primary:active:not(:disabled) {
+        transform: translateY(1px);
+      }
+      button.primary:disabled { 
+        opacity: 0.3; 
+        cursor: not-allowed; 
+      }
+      
+      .footer {
+        margin-top: 32px;
+        text-align: center;
+        font-size: 13px;
+        color: rgba(255,255,255,0.4);
+      }
+
+      /* Loading State Overlay */
+      .loading-overlay {
+        position: fixed;
+        top: 0; left: 0; right: 0; bottom: 0;
+        background: rgba(0, 0, 0, 0.85);
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        z-index: 100;
+        opacity: 0;
+        pointer-events: none;
+        backdrop-filter: blur(8px);
+        transition: opacity 0.3s ease;
+      }
+      .loading-overlay.active {
+        opacity: 1;
+        pointer-events: all;
+      }
+      
+      .loading-overlay .status-text {
+        font-size: 15px;
+        letter-spacing: 0.1em;
+        text-transform: uppercase;
+        color: #ffffff;
+        font-weight: 500;
+      }
+    </style>
+  </head>
+  <body>
+    <div class="wrap">
+      <div class="brand-header">
+        <svg
+          class="brand-mark"
+          viewBox="0 0 144 144"
+          role="img"
+          aria-label="Oh My Opencode Slim"
+        >
+          <rect
+            x="12"
+            y="12"
+            width="120"
+            height="120"
+            rx="32"
+            fill="rgba(255,255,255,0.08)"
+            stroke="rgba(255,255,255,0.18)"
+            stroke-width="2"
+          />
+          <path
+            d="M50 48h18c16 0 26 10 26 24s-10 24-26 24H50z"
+            fill="none"
+            stroke="white"
+            stroke-width="8"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+          />
+          <path
+            d="M74 48h20c10 0 18 8 18 18v12c0 10-8 18-18 18H74"
+            fill="none"
+            stroke="white"
+            stroke-width="8"
+            stroke-linecap="round"
+            stroke-linejoin="round"
+            opacity="0.65"
+          />
+        </svg>
+      </div>
+      <h1 id="idea">Connecting...</h1>
+      <p class="muted" id="summary">Preparing interview session</p>
+      
+      <div class="meta">
+        <span id="status">INITIALIZING</span>
+        <span>OH MY OPENCODE SLIM</span>
+      </div>
+      
+      <div id="filePathContainer" class="file-path-container" style="display: none;">
+        <span class="file-path-icon">📄</span>
+        <span id="markdownPath"></span>
+      </div>
+
+      <div id="questions"></div>
+      
+       <button class="primary" id="submitButton" disabled>Submit Answers <span class="submit-shortcut">⌘↵</span></button>
+      
+      <div class="footer" id="submitStatus"></div>
+    </div>
+    
+    <div class="loading-overlay" id="loadingOverlay">
+      <div class="status-text" id="loadingText">Processing...</div>
+    </div>
+
+    <script>
+      const interviewId = ${JSON.stringify(interviewId)};
+      const state = { data: null, answers: {}, activeQuestionIndex: 0, lastSig: null, customMode: {} };
+
+      function updateSubmitButton() {
+        const button = document.getElementById('submitButton');
+        if (!state.data) {
+          button.disabled = true;
+          return;
+        }
+
+        const questions = state.data.questions || [];
+        const allAnswered = questions.every((question) =>
+          (state.answers[question.id] || '').trim().length > 0,
+        );
+        button.disabled = state.data.isBusy || !questions.length || !allAnswered;
+        
+        const overlay = document.getElementById('loadingOverlay');
+        const overlayText = document.getElementById('loadingText');
+        if (state.data.isBusy) {
+          overlay.classList.add('active');
+          overlayText.textContent = "Agent Thinking...";
+        } else {
+          overlay.classList.remove('active');
+        }
+      }
+
+      function getOptionButtonId(questionId, index) {
+        return 'opt-' + questionId + '-' + index;
+      }
+
+      function createOption(question, option, index, isCustom) {
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.className = 'option';
+        button.id = getOptionButtonId(question.id, index);
+        
+        const shortcut = index < 9 ? (index + 1) : '';
+        if (shortcut) {
+          const kbd = document.createElement('span');
+          kbd.className = 'shortcut';
+          kbd.textContent = shortcut;
+          button.appendChild(kbd);
+        }
+        
+        const text = document.createElement('span');
+        text.className = 'option-text';
+        text.textContent = isCustom ? 'Custom' : option;
+        button.appendChild(text);
+
+        // Visual marking for suggested/recommended answers
+        if (!isCustom && question.suggested === option) {
+          const badge = document.createElement('span');
+          badge.className = 'recommended-badge';
+          badge.textContent = 'Recommended';
+          button.appendChild(badge);
+        }
+
+        button.addEventListener('click', () => {
+          const questions = state.data?.questions || [];
+          const qIdx = questions.findIndex(q => q.id === question.id);
+          if (qIdx !== -1) {
+             state.activeQuestionIndex = qIdx;
+             updateActiveQuestionFocus();
+          }
+          handleOptionSelect(question, option, isCustom);
+        });
+        
+        return button;
+      }
+
+      function handleOptionSelect(question, option, isCustom) {
+        const textarea = document.getElementById('answer-' + question.id);
+        
+        if (isCustom) {
+          state.customMode[question.id] = true;
+          state.answers[question.id] = state.customMode[question.id]
+            ? state.answers[question.id] || ''
+            : '';
+          updateTextareaVisibility(question.id);
+          updateOptionsDOM(question.id);
+          if (textarea) {
+            textarea.focus();
+          }
+        } else {
+          state.customMode[question.id] = false;
+          state.answers[question.id] = option;
+          updateTextareaVisibility(question.id);
+          advanceToNextQuestion(question.id);
+        }
+        
+        updateSubmitButton();
+        updateOptionsDOM(question.id);
+      }
+
+      function updateTextareaVisibility(questionId) {
+        const textarea = document.getElementById('answer-' + questionId);
+        if (!textarea) return;
+        if (state.customMode[questionId]) {
+          textarea.classList.remove('hidden-textarea');
+        } else {
+          textarea.classList.add('hidden-textarea');
+        }
+      }
+
+      function advanceToNextQuestion(currentQuestionId) {
+        const questions = state.data?.questions || [];
+        const currentIndex = questions.findIndex(q => q.id === currentQuestionId);
+        
+        if (currentIndex >= 0 && currentIndex < questions.length - 1) {
+          state.activeQuestionIndex = currentIndex + 1;
+          updateActiveQuestionFocus();
+          const nextQuestion = questions[currentIndex + 1];
+          const nextEl = document.getElementById('question-' + nextQuestion.id);
+          if (nextEl) {
+            nextEl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          }
+        } else if (currentIndex === questions.length - 1) {
+          const submitBtn = document.getElementById('submitButton');
+          if (submitBtn && !submitBtn.disabled) {
+            submitBtn.scrollIntoView({ behavior: 'smooth', block: 'center' });
+          }
+        }
+      }
+
+      function updateOptionsDOM(questionId) {
+        const question = (state.data?.questions || []).find(q => q.id === questionId);
+        if (!question) return;
+        
+        const predefined = question.options || [];
+        const currentAnswer = state.answers[question.id];
+        
+        predefined.forEach((opt, idx) => {
+           const btn = document.getElementById(getOptionButtonId(questionId, idx));
+           if (btn) {
+              if (currentAnswer === opt) btn.classList.add('selected');
+              else btn.classList.remove('selected');
+           }
+        });
+        
+        const customBtn = document.getElementById(getOptionButtonId(questionId, predefined.length));
+        if (customBtn) {
+           if (state.customMode[questionId]) {
+               customBtn.classList.add('selected');
+            } else {
+               customBtn.classList.remove('selected');
+           }
+        }
+      }
+
+      function updateActiveQuestionFocus() {
+         const questions = state.data?.questions || [];
+         questions.forEach((q, idx) => {
+            const wrapper = document.getElementById('question-' + q.id);
+            if (wrapper) {
+               if (idx === state.activeQuestionIndex) {
+                  wrapper.classList.add('active-question');
+               } else {
+                  wrapper.classList.remove('active-question');
+               }
+            }
+         });
+      }
+
+      document.addEventListener('keydown', (e) => {
+        const isSubmitShortcut =
+          (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) ||
+          (e.key === 's' && (e.metaKey || e.ctrlKey));
+        if (isSubmitShortcut) {
+          const submitBtn = document.getElementById('submitButton');
+          if (submitBtn && !submitBtn.disabled) {
+            submitBtn.click();
+            e.preventDefault();
+          }
+          return;
+        }
+
+        if (e.target.tagName === 'TEXTAREA' || e.target.tagName === 'INPUT') return;
+        if (e.ctrlKey || e.metaKey || e.altKey) return;
+
+        const questions = state.data?.questions || [];
+        if (!questions.length) return;
+
+         const num = parseInt(e.key, 10);
+         if (num >= 1 && num <= 9) {
+          const activeQ = questions[state.activeQuestionIndex];
+          if (!activeQ) return;
+          
+          const options = activeQ.options || [];
+          if (!options.length) return;
+
+          const idx = num - 1;
+          
+          if (idx < options.length) {
+            handleOptionSelect(activeQ, options[idx], false);
+            e.preventDefault();
+          } else if (idx === options.length) {
+            handleOptionSelect(activeQ, 'Custom', true);
+            e.preventDefault();
+         }
+
+        }
+        
+        if (e.key === 'ArrowDown') {
+           if (state.activeQuestionIndex < questions.length - 1) {
+              state.activeQuestionIndex++;
+              updateActiveQuestionFocus();
+              const wrapper = document.getElementById('question-' + questions[state.activeQuestionIndex].id);
+              if (wrapper) wrapper.scrollIntoView({ behavior: 'smooth', block: 'center' });
+              e.preventDefault();
+           }
+        }
+        if (e.key === 'ArrowUp') {
+           if (state.activeQuestionIndex > 0) {
+              state.activeQuestionIndex--;
+              updateActiveQuestionFocus();
+              const wrapper = document.getElementById('question-' + questions[state.activeQuestionIndex].id);
+              if (wrapper) wrapper.scrollIntoView({ behavior: 'smooth', block: 'center' });
+              e.preventDefault();
+           }
+        }
+      });
+
+      function renderQuestions(questions) {
+        const sig = JSON.stringify(questions);
+        const container = document.getElementById('questions');
+
+        if (state.lastSig === sig) {
+          questions.forEach((q) => updateOptionsDOM(q.id));
+          updateActiveQuestionFocus();
+          return;
+        }
+        
+        state.lastSig = sig;
+        container.replaceChildren();
+
+        if (!questions.length && !state.data?.isBusy) {
+          const empty = document.createElement('p');
+          empty.className = 'muted';
+          empty.style.textAlign = 'center';
+          empty.style.padding = '48px 0';
+          empty.textContent = 'No active questions right now.';
+          container.appendChild(empty);
+          return;
+        }
+
+        questions.forEach((question, idx) => {
+          const wrapper = document.createElement('div');
+          wrapper.className = 'question';
+          wrapper.id = 'question-' + question.id;
+          
+           if (question.suggested && !state.answers[question.id]) {
+             state.answers[question.id] = question.suggested;
+             state.customMode[question.id] = false;
+            }
+
+          const title = document.createElement('h3');
+          title.textContent = question.question;
+          wrapper.appendChild(title);
+
+          const predefined = question.options || [];
+          if (predefined.length) {
+            const options = document.createElement('div');
+            options.className = 'options';
+            predefined.forEach((option, optIdx) => {
+              options.appendChild(createOption(question, option, optIdx, false));
+            });
+            options.appendChild(createOption(question, 'Custom', predefined.length, true));
+            wrapper.appendChild(options);
+          }
+
+           const textarea = document.createElement('textarea');
+           textarea.id = 'answer-' + question.id;
+           textarea.placeholder = 'Type your answer here...';
+           textarea.value = state.customMode[question.id] ? (state.answers[question.id] || '') : '';
+           if (!state.customMode[question.id]) {
+             textarea.classList.add('hidden-textarea');
+           }
+           
+           textarea.addEventListener('focus', () => {
+              state.activeQuestionIndex = idx;
+            updateActiveQuestionFocus();
+          });
+          
+          textarea.addEventListener('input', () => {
+            state.answers[question.id] = textarea.value;
+            updateSubmitButton();
+            updateOptionsDOM(question.id);
+          });
+          wrapper.appendChild(textarea);
+
+          container.appendChild(wrapper);
+        });
+        
+        updateActiveQuestionFocus();
+        questions.forEach(q => updateOptionsDOM(q.id));
+      }
+
+      function render(data) {
+        state.data = data;
+        document.getElementById('idea').textContent = data.interview.idea || 'Interview';
+        document.getElementById('summary').textContent = data.summary || 'Session in progress.';
+        document.getElementById('status').textContent = data.mode.toUpperCase();
+        
+        // Render Markdown Path
+        const pathContainer = document.getElementById('filePathContainer');
+        const pathElement = document.getElementById('markdownPath');
+        const mdPath = data.markdownPath || (data.interview && data.interview.markdownPath);
+        if (mdPath) {
+          pathElement.textContent = mdPath;
+          pathContainer.style.display = 'flex';
+        } else {
+          pathContainer.style.display = 'none';
+        }
+        
+        renderQuestions(data.questions || []);
+        updateSubmitButton();
+      }
+
+      async function refresh() {
+        const response = await fetch('/api/interviews/' + encodeURIComponent(interviewId) + '/state');
+        const data = await response.json();
+        if (!response.ok) throw new Error(data.error || 'Failed to load state');
+        render(data);
+      }
+
+      document.getElementById('submitButton').addEventListener('click', async () => {
+        if (!state.data) return;
+        const answers = (state.data.questions || []).map((question) => {
+          return {
+            questionId: question.id,
+            answer: (state.answers[question.id] || '').trim(),
+          };
+        });
+
+        const overlay = document.getElementById('loadingOverlay');
+        const overlayText = document.getElementById('loadingText');
+        overlay.classList.add('active');
+        overlayText.textContent = "Submitting Answers...";
+
+        try {
+          const response = await fetch('/api/interviews/' + encodeURIComponent(interviewId) + '/answers', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ answers }),
+          });
+          const payload = await response.json();
+          document.getElementById('submitStatus').textContent = payload.message || (response.ok ? 'Answers submitted successfully.' : 'Submission failed.');
+        } catch (err) {
+          document.getElementById('submitStatus').textContent = 'Error submitting answers.';
+        }
+        try {
+          await refresh();
+        } catch (_error) {
+          overlay.classList.remove('active');
+        }
+      });
+
+      refresh().catch((error) => {
+        document.getElementById('submitStatus').textContent = error.message || 'Failed to load interview.';
+      });
+      setInterval(() => {
+        refresh().catch(() => {});
+      }, 2500);
+    </script>
+  </body>
+</html>`;
+}