@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/scripts/check-release.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+import { readFile } from 'node:fs/promises';
+import { realpathSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+export const repositoryRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const releaseVersionPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+export async function checkRelease({ root = repositoryRoot, env = process.env } = {}) {
+  const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+  const lock = JSON.parse(await readFile(path.join(root, 'package-lock.json'), 'utf8'));
+  if (!releaseVersionPattern.test(pkg.version) || lock.version !== pkg.version || lock.packages?.['']?.version !== pkg.version) {
+    throw Error('package.json and package-lock.json must have the same X.Y.Z release version.');
+  }
+  // The engine's renderer runs on the package's puppeteer, so the two pins must agree.
+  const engine = JSON.parse(await readFile(path.join(root, 'engine', 'generate-illustrated-article', 'package.json'), 'utf8'));
+  if (engine.dependencies?.puppeteer !== pkg.dependencies?.puppeteer) {
+    throw Error(`package.json must pin puppeteer ${engine.dependencies?.puppeteer} to match engine/generate-illustrated-article.`);
+  }
+  // MCP Registry metadata names the same package version.
+  let server;
+  try { server = JSON.parse(await readFile(path.join(root, 'server.json'), 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (server && (server.version !== pkg.version || server.packages?.some(entry => entry.version !== pkg.version))) {
+    throw Error(`server.json must use version ${pkg.version} for the server and its packages.`);
+  }
+  const tagged = env.GITHUB_REF_TYPE === 'tag';
+  if (tagged && env.GITHUB_REF_NAME !== `v${pkg.version}`) {
+    throw Error(`Release tag must be v${pkg.version}, matching package.json.`);
+  }
+  if (env.CLI_RELEASE_PUBLISH === 'true' && !tagged) {
+    throw Error('Publishing requires a vX.Y.Z tag. Run a build-only workflow on branches.');
+  }
+  return pkg.version;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  process.stdout.write(`${await checkRelease()}\n`);
+}

package/scripts/check-runtime.mjs

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+// Run by the installer before switching releases: the bundled Node must be able
+// to run the article renderer on this machine.
+try {
+  const [major, minor] = process.versions.node.split('.').map(Number);
+  if (!(major > 22 || major === 22 && minor >= 12)) throw Error('The local article renderer requires Node.js 22.12 or later.');
+} catch (error) {
+  process.stderr.write(error.message + '\n');
+  process.exitCode = 1;
+}

package/scripts/cli.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+// `wtfm mcp [options]` (or the `supportpages` alias) runs the stdio MCP server, so MCP clients and
+// registries can launch it through the package's single command (npx).
+if (process.argv[2] === 'mcp') {
+  const server = new URL('../dist/index.js', import.meta.url);
+  process.argv.splice(1, 2, (await import('node:url')).fileURLToPath(server));
+  await import(server.href);
+} else await import('./lib/cli-main.mjs');

package/scripts/install.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createTerminal, Cancelled } from './lib/terminal.mjs';
+import { runInstaller } from './lib/install.mjs';
+import { CLI_NAME } from './lib/brand.mjs';
+
+const help = `SupportPages Writer — guided local setup
+
+Usage: ./install.sh [options]
+       node scripts/install.mjs [options]
+
+The wizard builds the MCP server, prepares the article engine, and connects your coding
+client globally. Optionally connect a repository through browser setup. Run it from a terminal on macOS or Linux.
+
+  --workspace PATH       Connect this repository after installation
+  --client NAME          codex, claude, both, or manual (auto-detected menu)
+  --dev                  Connect to local RTFM (https://app.lvh.me:3443)
+  --api-url URL          SupportPages.io app origin (default: https://app.supportpages.io)
+  --skills-dir PATH      Use another engine directory instead of the bundled one
+  --name NAME            Custom MCP connection name (default: supportpages or supportpages-dev)
+  --skip-skills          Skip the trace hook and Chromium download
+  --skip-dependencies    Use an already-built MCP checkout without npm ci/build
+  --config-dir PATH      Private settings directory (~/.config/supportpages)
+  --data-dir PATH        Installation data (~/.local/share/supportpages)
+  --yes                  Noninteractive; requires --client
+  -h, --help             Show this help without installing anything
+
+Installation does not sign you in. Afterwards run ${CLI_NAME} setup once on this
+computer, then ${CLI_NAME} init inside each project folder, or ask your coding
+client to initialize SupportPages.io. Articles can be saved in the project without
+an account; signing in (browser approval, private credentials) is needed only to
+host them on a help centre.
+`;
+let options;
+try {
+  const stringOptions = ['workspace', 'client', 'api-url', 'skills-dir', 'name', 'config-dir', 'data-dir'];
+  const booleanOptions = ['dev', 'skip-skills', 'skip-dependencies', 'yes'];
+  options = parseArgs({ options: {
+    ...Object.fromEntries(stringOptions.map(name => [name, { type: 'string' }])),
+    ...Object.fromEntries(booleanOptions.map(name => [name, { type: 'boolean' }])),
+    help: { type: 'boolean', short: 'h' },
+  }}).values;
+} catch {
+  process.stderr.write('Invalid installer options. Run ./install.sh --help. Authentication happens in your browser.\n');
+  process.exitCode = 2;
+}
+if (options) {
+  if (options.help) process.stdout.write(help);
+  else {
+    try {
+      if (process.platform === 'win32') throw new Error('Run this installer in WSL. The skills currently require a Unix shell.');
+      const [nodeMajor, nodeMinor] = process.versions.node.split('.').map(Number);
+      if (nodeMajor < 22 || nodeMajor === 22 && nodeMinor < 12) throw new Error('Node.js 22.12 or later is required.');
+      process.env.PATH = path.dirname(process.execPath) + path.delimiter + (process.env.PATH ?? '');
+      if (!options.yes && (!process.stdin.isTTY || !process.stdout.isTTY)) throw new Error('Run ./install.sh in a terminal, or use --yes with explicit options.');
+      await runInstaller(options, { ui: createTerminal(), installRoot: path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..') });
+    } catch (error) {
+      process.stderr.write(`\n${error instanceof Cancelled ? '' : 'Setup stopped: '}${error.message}\n`);
+      process.exitCode = error instanceof Cancelled ? 130 : 1;
+    }
+  }
+}

package/scripts/lib/agent-runner.mjs

@@ -0,0 +1,181 @@
+import { spawn } from 'node:child_process';
+import { open } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import readline from 'node:readline';
+import { modelSettings } from './agent-settings.mjs';
+import { Cancelled } from './terminal.mjs';
+import { fail } from '../../dist/errors.js';
+import { claudeWriterAgents } from '../../dist/writer-agent.js';
+
+// Display observed activity, never raw commands, agent prose or reasoning.
+export function agentActivity(event) {
+  const commandActivity = command => {
+    if (/classify_app_type\.(sh|js)/.test(command ?? '')) return 'Detecting app type';
+    if (/detect_static\.js/.test(command ?? '')) return 'Detecting project branding';
+    if (/(compile_css\.sh|run_css_build\.sh|check_css_health\.js)/.test(command ?? '')) return 'Preparing project styles';
+    if (/(detect_structure\.js|apply_runtime_profiles\.js)/.test(command ?? '')) return 'Mapping project structure';
+    return 'Running project commands';
+  };
+  if (event.type === 'system' && event.subtype === 'init' || event.type === 'turn.started') return 'Inspecting the project';
+  if (event.type === 'system' && event.subtype === 'thinking_tokens') return 'Analysing the project';
+  if (event.type === 'assistant') {
+    const tool = event.message?.content?.find(item => item.type === 'tool_use');
+    if (tool?.name === 'Bash') return commandActivity(tool.input?.command);
+    if (['Read', 'Glob', 'Grep'].includes(tool?.name)) return 'Reading project files';
+    if (['Write', 'Edit', 'MultiEdit'].includes(tool?.name)) return /(?:summary\.md|overview\.txt)$/.test(tool.input?.file_path ?? '') ? 'Writing the product summary' : 'Saving project files';
+  }
+  if (['item.started', 'item.updated', 'item.completed'].includes(event.type)) {
+    if (event.item?.type === 'command_execution') return event.type === 'item.completed' ? 'Reviewing command results' : commandActivity(event.item.command);
+    if (event.item?.type === 'file_change') return 'Saving project files';
+    if (event.item?.type === 'agent_message') return 'Preparing the agent response';
+    if (event.type === 'item.started') return 'Inspecting the project';
+  }
+}
+
+export function agentProgressText(agent, activity, elapsedMs, quietMs = 0) {
+  const seconds = Math.floor(elapsedMs / 1000);
+  const elapsed = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+  const quiet = quietMs >= 20000 ? ` · Last update ${Math.floor(quietMs / 1000)}s ago` : '';
+  return `${agent === 'claude' ? 'Claude Code' : 'Codex'} · ${activity} · ${elapsed} elapsed${quiet} · Ctrl+C to cancel`;
+}
+
+export function agentCommand(agent, { interactive = false, prompt = '', model, effort, disabledConnection } = {}) {
+  if (!['claude', 'codex'].includes(agent)) fail('invalid_agent', 'Choose Claude Code or Codex.');
+  if (disabledConnection !== undefined && !['supportpages', 'supportpages-dev'].includes(disabledConnection)) fail('invalid_configuration', 'Invalid SupportPages.io connection.');
+  const permissionFlag = agent === 'claude' ? '--dangerously-skip-permissions' : '--dangerously-bypass-approvals-and-sandbox';
+  ({ model, effort } = modelSettings(agent, { model, effort }));
+  const flags = [...(interactive ? [] : [permissionFlag]), ...(model ? ['--model', model] : []),
+    ...(disabledConnection ? agent === 'claude' ? ['--disallowedTools', `mcp__${disabledConnection}`] : ['-c', `mcp_servers.${disabledConnection}.enabled=false`] : []),
+    ...(effort ? agent === 'claude' ? ['--effort', effort] : ['-c', `model_reasoning_effort=${JSON.stringify(effort)}`] : [])];
+  if (interactive) return { command: agent, args: [...flags, ...(agent === 'claude' ? ['--agents', JSON.stringify(claudeWriterAgents)] : []), prompt] };
+  return agent === 'claude'
+    ? { command: 'claude', args: ['-p', '--verbose', '--output-format', 'stream-json', ...flags] }
+    : { command: 'codex', args: ['exec', '-', '--json', ...flags] };
+}
+
+/** Run locally with the user's auth and permission checks bypassed. */
+export async function runAgent({ agent, model, effort, workspace, prompt, env, logPath, ui, timeoutMs = 15 * 60_000, spawnProcess = spawn, signal, manageTerminal = true }) {
+  if (signal?.aborted) throw new Cancelled();
+  const invocation = agentCommand(agent, { model, effort });
+  const log = await open(logPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+  const childEnv = { ...env };
+  delete childEnv.SUPPORTPAGES_API_TOKEN;
+  delete childEnv.SUPPORTPAGES_API_TOKEN_FILE;
+  let child, interrupted = false, timedOut = false, streamError = false, permissionBlocked = false, failed = false, completed = false, buffer = '', logBytes = 0;
+  let forceTimer, timer, heartbeat, progress, agentFinished = false, logWork = Promise.resolve();
+  const started = Date.now();
+  let activity = 'Starting agent', lastEvent = started, lastRendered = started;
+  const progressText = () => agentProgressText(agent, activity, Date.now() - started, Date.now() - lastEvent);
+  const render = (isHeartbeat = false) => {
+    if (progress) progress.update(progressText(), { heartbeat: isHeartbeat });
+    else if (!isHeartbeat || Date.now() - lastRendered >= 15000) { ui.info?.(progressText()); lastRendered = Date.now(); }
+  };
+  const record = text => {
+    if (logBytes > 8 * 1024 * 1024) return;
+    logBytes += Buffer.byteLength(text);
+    logWork = logWork.then(() => log.write(text)).catch(() => { streamError = true; });
+  };
+  const signalGroup = signal => {
+    if (!child?.pid) return;
+    try { process.kill(-child.pid, signal); } catch { try { child.kill(signal); } catch {} }
+  };
+  const stop = () => { signalGroup('SIGTERM'); forceTimer ??= setTimeout(() => signalGroup('SIGKILL'), 1500); };
+  const cancel = () => { interrupted = true; stop(); };
+  const keypress = (_text, key) => { if (key?.ctrl && ['c', 'd'].includes(key.name)) cancel(); };
+  const input = process.stdin;
+  const wasRaw = Boolean(input.isRaw), wasFlowing = input.readableFlowing === true;
+  try {
+    child = spawnProcess(invocation.command, invocation.args, { cwd: workspace, env: childEnv, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    if (manageTerminal) { process.once('SIGINT', cancel); process.once('SIGTERM', cancel); }
+    signal?.addEventListener('abort', cancel, { once: true });
+    if (signal?.aborted) cancel();
+    if (manageTerminal && input.isTTY && input.setRawMode) {
+      readline.emitKeypressEvents(input);
+      input.setRawMode(true); input.on('keypress', keypress); input.resume();
+    }
+    timer = setTimeout(() => { timedOut = true; stop(); }, timeoutMs);
+    heartbeat = setInterval(() => render(true), 1000);
+    const event = line => {
+      if (!line.trim()) return;
+      let value;
+      try { value = JSON.parse(line); } catch { streamError = true; return; }
+      if (!value || typeof value !== 'object' || Array.isArray(value)) { streamError = true; return; }
+      lastEvent = Date.now();
+      if (value.type === 'system' && value.subtype === 'permission_denied') {
+        // Headless mode cannot ask for approval. Stop promptly and let the user
+        // approve in their interactive agent, rather than retrying other tools.
+        permissionBlocked = true; activity = 'Permission required'; render(); stop();
+      }
+      if (value.type === 'result') {
+        completed = true;
+        // permission_denials is historical: a successful run may have recovered.
+        // Success still requires the caller's artifact validation.
+        failed ||= value.is_error === true || (value.is_error !== false && value.subtype !== 'success');
+        if (failed && value.permission_denials?.length > 0) permissionBlocked = true;
+      }
+      if (value.type === 'turn.completed') completed = true;
+      if (['turn.failed', 'error'].includes(value.type)) failed = true;
+      const nextActivity = agentActivity(value);
+      if (nextActivity && nextActivity !== activity) { activity = nextActivity; render(); }
+    };
+    child.stdout.on('data', chunk => {
+      const text = chunk.toString(); record(text); buffer += text;
+      if (buffer.length > 1024 * 1024) { streamError = true; stop(); return; }
+      let newline;
+      while ((newline = buffer.indexOf('\n')) >= 0) { event(buffer.slice(0, newline)); buffer = buffer.slice(newline + 1); }
+    });
+    child.stderr.on('data', chunk => record(chunk.toString()));
+    child.stdin.on('error', () => {}); // EPIPE is reported through the child's final status.
+    const done = new Promise((resolve, reject) => {
+      child.once('error', reject);
+      child.once('close', (code, signal) => resolve({ code, signal }));
+    });
+    progress = ui.progress?.(progressText());
+    if (!progress) render();
+    child.stdin.end(prompt);
+    let result;
+    try { result = await done; }
+    catch { fail('agent_unavailable', `Could not start ${agent}. Check its installation, sign in, and retry.`); }
+    if (buffer.trim()) event(buffer);
+    await logWork;
+    if (interrupted) throw new Cancelled();
+    if (permissionBlocked) fail('agent_permission_required', 'Claude Code needs tool or file-access approval to continue. Open it interactively to review the requested permissions. Your completed setup steps are kept.');
+    if (timedOut) fail('agent_timeout', 'The agent timed out. Completed setup steps are saved; retry this stage.');
+    if (result.code !== 0 || failed || !completed || streamError) fail('agent_failed', `The agent could not complete this stage. Open ${agent} in this project to check authentication and permissions, then retry. Private diagnostics: ${logPath}`);
+    agentFinished = true;
+  } finally {
+    clearTimeout(timer); clearTimeout(forceTimer); clearInterval(heartbeat);
+    // Kill remaining descendants after cancellation, even if the leader exited first.
+    if (interrupted || timedOut || streamError || permissionBlocked) signalGroup('SIGKILL');
+    if (manageTerminal) {
+      process.off('SIGINT', cancel); process.off('SIGTERM', cancel);
+      input.off('keypress', keypress);
+      if (input.isTTY && input.setRawMode) { input.setRawMode(wasRaw); if (!wasFlowing) input.pause(); }
+    }
+    signal?.removeEventListener('abort', cancel);
+    const elapsed = Math.floor((Date.now() - started) / 1000);
+    const message = `${interrupted ? 'Agent stopped' : permissionBlocked ? 'Agent needs permission to continue' : timedOut ? 'Agent timed out' : agentFinished ? 'Agent finished; checking its outputs next' : 'Agent could not finish'} · ${elapsed}s elapsed`;
+    if (progress) progress.stop(message, interrupted ? 'cancelled' : agentFinished ? 'success' : 'error');
+    else ui.info?.(message);
+    await logWork; await log.close();
+  }
+}
+
+export async function openAgent({ agent, model, effort, workspace, prompt, env, ui, disabledConnection, spawnProcess = spawn }) {
+  const { command, args } = agentCommand(agent, { interactive: true, prompt, model, effort, disabledConnection });
+  try {
+    const child = spawnProcess(command, args, { cwd: workspace, env, stdio: 'inherit' });
+    const ignoreInterrupt = () => {}; // Foreground agent owns the terminal while it is open.
+    process.on('SIGINT', ignoreInterrupt);
+    try {
+      const code = await new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
+      if (code !== 0) throw Error('Agent exited');
+    } finally { process.off('SIGINT', ignoreInterrupt); }
+    return true;
+  } catch {
+    const quote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+    const manualCommand = [command, ...args.slice(0, -1)].map(quote).join(' ');
+    ui.line(`Open your coding agent manually:\ncd ${quote(workspace)}\n${manualCommand}\n\nThen paste:\n${prompt}`);
+    return false;
+  }
+}

package/scripts/lib/agent-settings.mjs

@@ -0,0 +1,215 @@
+import { fail } from '../../dist/errors.js';
+import { discoverModels } from './harness-models.mjs';
+import { Cancelled } from './terminal.mjs';
+
+export const agentLabel = agent => agent === 'claude' ? 'Claude Code' : 'Codex';
+import { efforts, modelValid, settingsFile, modelSettings, readAgentSettings } from '../../dist/agent-settings.js';
+import { CLI_NAME } from './brand.mjs';
+export { modelSettings, readAgentSettings, executionSettings } from '../../dist/agent-settings.js';
+
+// Preferred families for articles, best first: Opus then Fable on Claude Code, Sol
+// then Astra on Codex (today Opus 5.5 and GPT-6-Sol). Catalogue order and isDefault
+// are not rankings. Only recommend IDs actually exposed by the coding agent.
+function recommendedModel(agent, models) {
+  const families = agent === 'claude' ? ['opus', 'fable'] : ['sol', 'astra'];
+  for (const family of families) {
+    const pattern = agent === 'claude'
+      ? new RegExp(`^(?:${family}|claude-${family}-\\d+(?:[.-]\\d+)*)(?:\\[[^\\]]+\\])?$`)
+      : new RegExp(`^gpt-\\d+(?:\\.\\d+)?-${family}$`);
+    const matches = models.filter(({ value }) => pattern.test(value));
+    if (!matches.length) continue;
+    // Claude's explicit family alias follows its current release. Otherwise
+    // choose the newest version within the family, independently of list order.
+    return matches.find(model => model.value === family)
+      ?? matches.find(model => model.value === `${family}[1m]`)
+      ?? matches.sort((a, b) => b.value.localeCompare(a.value, 'en', { numeric: true }))[0];
+  }
+}
+
+function modelHint(agent, model, recommended) {
+  if (model.value === recommended?.value) return 'Recommended for faithful mockups and detailed articles. Use Medium effort when available.';
+  const lighter = agent === 'claude'
+    ? /^(?:(?:sonnet|haiku)|claude-(?:sonnet|haiku)-\d+(?:[.-]\d+)*)(?:\[[^\]]+\])?$/.test(model.value)
+    : /^gpt-\d+(?:\.\d+)?-(?:terra|luna)$/.test(model.value);
+  return lighter ? 'Suitable for rough drafts and simpler mockups. Expect more review and visual corrections.' : model.hint;
+}
+
+const effortHints = {
+  minimal: 'For quick drafts where approximate mockups are acceptable.',
+  low: 'For quick drafts where approximate mockups are acceptable.',
+  medium: 'Our recommended starting point for faithful mockups and article quality.',
+  high: 'Allow more reasoning for complex interfaces. Generation can take longer.',
+  xhigh: 'Allow more reasoning for complex interfaces. Generation can take longer.',
+  max: 'Allow more reasoning for complex interfaces. Generation can take longer.',
+};
+
+export function modelDescription(agent, settings) {
+  const { model, effort } = modelSettings(agent, settings);
+  return `${agentLabel(agent)} · ${model ?? 'agent-configured model'} · ${effort ? `${effort} effort` : 'agent-configured effort'}`;
+}
+
+export async function availableAgents(session, deps, clients = []) {
+  const available = [];
+  for (const agent of ['claude', 'codex']) {
+    if (clients.length && !clients.includes(agent)) continue;
+    if ((await deps.run(agent, ['--version'], { capture: true })).code !== 0) continue;
+    if (!clients.length && (await deps.run(agent, ['mcp', 'get', session.options.dev ? 'supportpages-dev' : 'supportpages'], { capture: true })).code !== 0) continue;
+    available.push(agent);
+  }
+  if (!available.length) fail('agent_unavailable', `No coding agent is connected yet. Install Claude Code or Codex, then run ${CLI_NAME} setup to connect it.`);
+  return available;
+}
+
+/**
+ * With both agents connected, ask which runs project analysis. Claude Code is listed
+ * first and preselected unless this project already chose; writing always uses
+ * whichever agent the user is working in.
+ */
+async function chooseAnalysisAgent(ui, clients, preferred) {
+  if (clients.length < 2) return clients[0];
+  const ordered = [...clients].sort((a, b) => (b === 'claude') - (a === 'claude'));
+  const initial = clients.includes(preferred) ? preferred : ordered[0];
+  ui.line(`Project analysis runs in one agent and becomes the default for ${CLI_NAME} analyse. When you write, SupportPages uses whichever agent you are working in.`);
+  return ui.choose('Which coding agent should run project analysis?', ordered.map(value => ({ value, label: agentLabel(value),
+    ...(value === 'claude' ? { hint: 'Recommended' } : {}) })), ordered.indexOf(initial));
+}
+
+export async function configureAgent(session, deps, { clients = [], agent: requestedAgent } = {}) {
+  const bridge = await session.bridge(), saved = await readAgentSettings(bridge);
+  const available = await availableAgents(session, deps, clients);
+  const { ui } = deps;
+  if (requestedAgent && !available.includes(requestedAgent)) fail('agent_unavailable', `The selected coding agent is not connected. Run ${CLI_NAME} setup to connect it.`);
+  const preferred = requestedAgent ?? saved.agent;
+  const agent = available.length === 1
+    ? available[0]
+    : await ui.choose('Coding agent for this project', available.map(value => ({ value, label: agentLabel(value) })), Math.max(0, available.indexOf(preferred)));
+  const settings = await chooseModelSettings(agent, saved, bridge, deps);
+  // Commit only after all prompts succeed; keep settings for the other agent.
+  await bridge.ws.writeJson(settingsFile(bridge), { ...saved,
+    ...(saved.agents ? { agents: [...new Set([...saved.agents, agent])] } : {}),
+    agent, models: { ...saved.models, [agent]: settings } });
+  ui.ok(`Saved for this project: ${modelDescription(agent, settings)}.`);
+  return { agent, ...settings };
+}
+
+/** Init configures every selected integration before committing project choices. */
+export async function configureAgents(session, deps, { clients, agent: requestedAgent } = {}) {
+  const bridge = await session.bridge(), saved = await readAgentSettings(bridge);
+  const available = await availableAgents(session, deps, clients);
+  if (available.length !== clients.length) fail('agent_unavailable', `A selected coding agent is no longer available. Run ${CLI_NAME} init again.`);
+  const models = { ...saved.models };
+  for (const agent of clients) {
+    deps.ui.line(`Configure ${agentLabel(agent)} for this project.`);
+    models[agent] = await chooseModelSettings(agent, saved, bridge, deps);
+  }
+  const agent = await chooseAnalysisAgent(deps.ui, clients, requestedAgent ?? saved.agent);
+  await bridge.ws.writeJson(settingsFile(bridge), { ...saved, agents: clients, agent, models });
+  for (const client of clients) deps.ui.ok(`Saved for this project: ${modelDescription(client, models[client])}.`);
+  return { agent, models };
+}
+
+/** The recommended model with Medium effort when the catalogue supports it, without prompting. */
+export function quietModelSettings(agent, discovered) {
+  const recommended = recommendedModel(agent, discovered);
+  const model = recommended?.value ?? discovered.find(entry => entry.isDefault)?.value ?? null;
+  const metadata = discovered.find(entry => entry.value === model);
+  const effort = (metadata?.efforts ?? efforts[agent]).includes('medium') ? 'medium' : null;
+  return modelSettings(agent, { model, effort });
+}
+
+/** How init names a model: the agent's own label when it lists the model. */
+function describeModel(agent, settings, discovered) {
+  const model = settings.model === null ? `${agentLabel(agent)}’s default model`
+    : discovered.find(entry => entry.value === settings.model)?.label ?? settings.model;
+  const effort = settings.effort ? `${settings.effort[0].toUpperCase()}${settings.effort.slice(1)} effort` : 'its default effort';
+  return `${model} at ${effort}`;
+}
+
+/**
+ * Init: state each agent's model for this project (the saved choice, or the
+ * recommended one) and ask whether to change it. Nothing is saved until every
+ * question is answered.
+ */
+export async function confirmAgentModels(session, deps, { clients, agent: requestedAgent } = {}) {
+  const bridge = await session.bridge(), saved = await readAgentSettings(bridge);
+  const available = await availableAgents(session, deps, clients);
+  if (available.length !== clients.length) fail('agent_unavailable', `A selected coding agent is no longer available. Run ${CLI_NAME} setup to repair it.`);
+  const { ui } = deps;
+  const models = { ...saved.models };
+  for (const agent of clients) {
+    ui.info?.(`Getting available models from ${agentLabel(agent)}…`);
+    let discovered = [];
+    try { discovered = await (deps.discoverModels ?? discoverModels)(agent, { cwd: bridge.ws.root, env: deps.env }); }
+    catch (error) { if (error instanceof Cancelled) throw error; }
+    let current;
+    try { current = saved.models?.[agent] ? modelSettings(agent, saved.models[agent]) : undefined; }
+    catch { current = undefined; }
+    current ??= quietModelSettings(agent, discovered);
+    if (!discovered.length && !saved.models?.[agent]) ui.line(`Could not get the model list from ${agentLabel(agent)}, so it will use its own default model. Check its sign-in and version to choose one.`);
+    ui.line(`${agentLabel(agent)} will write this project’s articles with ${describeModel(agent, current, discovered)}.`);
+    models[agent] = await ui.confirm(`Change the ${agentLabel(agent)} model?`, false)
+      ? await chooseModelSettings(agent, saved, bridge, deps, discovered)
+      : current;
+  }
+  // The analysis step asks which agent runs it; until then keep the project's choice,
+  // or default to Claude Code.
+  const preferred = requestedAgent ?? saved.agent;
+  const agent = clients.includes(preferred) ? preferred : clients.includes('claude') ? 'claude' : clients[0];
+  await bridge.ws.writeJson(settingsFile(bridge), { ...saved, agents: clients, agent, models });
+  return { agent, models };
+}
+
+async function chooseModelSettings(agent, saved, bridge, deps, listed) {
+  const { ui } = deps;
+  // Allow configure to repair an obsolete model or effort selection.
+  let current;
+  try { current = modelSettings(agent, saved.models?.[agent] ?? {}); }
+  catch { current = modelSettings(agent); }
+  let discovered = listed ?? [];
+  // Init passes the catalogue it has just listed; an empty one is retried here.
+  if (!discovered.length) try {
+    ui.info?.(`Getting available models from ${agentLabel(agent)}…`);
+    discovered = await (deps.discoverModels ?? discoverModels)(agent, { cwd: bridge.ws.root, env: deps.env });
+  } catch (error) {
+    if (error instanceof Cancelled) throw error;
+    ui.line(`Could not get models from ${agentLabel(agent)}. You can keep your saved model, use the agent-configured model, or enter a model name. Check your coding agent's sign-in and version, then retry with ${CLI_NAME} configure.`);
+  }
+  const recommended = recommendedModel(agent, discovered);
+  const models = [
+    ...discovered.map(model => ({ ...model,
+      label: model.value === recommended?.value ? `${model.label} — Recommended for SupportPages.io` : model.label,
+      hint: modelHint(agent, model, recommended) })),
+    ...(saved.models?.[agent]?.model && current.model && !discovered.some(m => m.value === current.model)
+      ? [{ value: current.model, label: `${current.model} (current setting)`, hint: 'Not listed by the coding agent' }] : []),
+    { value: 'inherit', label: 'Use my coding agent’s default model', hint: 'Mockup fidelity will depend on your coding agent’s model choice.' },
+    { value: 'custom', label: 'Enter a model name', hint: 'For a model you already know you want to use' },
+  ];
+  const selected = saved.models?.[agent]?.model !== undefined
+    ? current.model === null ? 'inherit' : models.some(m => m.value === current.model) ? current.model : 'custom'
+    : recommended?.value ?? discovered.find(m => m.isDefault)?.value ?? 'inherit';
+  ui.line('Your model analyses the application and creates the article’s illustrated mockups. Lighter models may simplify layouts or miss interface details.');
+  if (recommended) ui.line(`For faithful mockups, SupportPages.io recommends ${recommended.label} with Medium effort when supported.`);
+  else if (discovered.length) ui.line('We could not identify a recommended model in this catalogue. Choose an available model or use your agent’s default.');
+  const choice = await ui.choose(`${agentLabel(agent)} model`, models, models.findIndex(m => m.value === selected));
+  const model = choice === 'inherit' ? null : choice === 'custom'
+    ? (await ui.ask('Model name', current.model ?? '', { validate: value => modelValid(value.trim()) ? undefined : 'Enter a model name, without spaces or flags.' })).trim()
+    : choice;
+  const metadata = discovered.find(item => item.value === model);
+  const effortOptions = [
+    ...(metadata?.efforts ?? efforts[agent]).map(value => ({ value,
+      label: `${value[0].toUpperCase()}${value.slice(1)}${value === 'medium' ? ' — Recommended for SupportPages.io' : ''}`,
+      hint: effortHints[value] })),
+    { value: 'inherit', label: 'Use my coding agent’s default effort' },
+  ];
+  const preferredEffort = saved.models?.[agent]?.effort === null ? 'inherit'
+    : saved.models?.[agent]?.effort === undefined && model === recommended?.value
+      ? effortOptions.some(e => e.value === 'medium') ? 'medium' : metadata?.defaultEffort ?? 'inherit'
+    : effortOptions.some(e => e.value === current.effort) ? current.effort
+    : metadata?.defaultEffort ?? 'inherit';
+  ui.line(effortOptions.some(e => e.value === 'medium')
+    ? 'Reasoning effort controls how much time the model spends thinking. We recommend Medium for mockups; higher settings can take longer.'
+    : 'This model does not list Medium effort. Choose a supported effort or use your coding agent’s default.');
+  const effortChoice = await ui.choose('Reasoning effort', effortOptions, Math.max(0, effortOptions.findIndex(e => e.value === preferredEffort)));
+  const settings = modelSettings(agent, { model, effort: effortChoice === 'inherit' ? null : effortChoice });
+  return settings;
+}

package/scripts/lib/article-skills.mjs

@@ -0,0 +1,82 @@
+import path from 'node:path';
+import { readFile, readlink, realpath, rm } from 'node:fs/promises';
+
+export const ARTICLE_SKILLS = ['detect-project', 'generate-illustrated-article'];
+const retired = ['suggest-sections', 'recommend-articles', 'recommend-walkthroughs', 'generate-walkthrough', 'generate-card-backgrounds'];
+
+export async function retirePublicSkillLinks({ home, clients, directory, previousDirectory, env = {}, dryRun = false }) {
+  const canonical = async value => {
+    try { return await realpath(value); } catch (error) { if (error.code === 'ENOENT') return path.resolve(value); throw error; }
+  };
+  const roots = await Promise.all([directory, previousDirectory].filter(Boolean).map(canonical));
+  const anchor = path.join(home, '.rtfm-skills');
+  // Older receipts omitted skills_dir, and MCP may now point at a worktree.
+  // The managed engine shortcut still identifies those earlier public links.
+  try { roots.push(await canonical(path.resolve(home, await readlink(anchor))), anchor); }
+  catch (error) { if (!['ENOENT', 'EINVAL'].includes(error.code)) throw error; }
+  const removed = [];
+  const discoveries = new Set(clients.flatMap(selected => selected === 'claude'
+    ? [path.join(home, '.claude/skills'), path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'skills')]
+    : [path.join(home, '.agents/skills'), path.join(home, '.codex/skills'), path.join(env.CODEX_HOME || path.join(home, '.codex'), 'skills')]));
+  for (const discovery of discoveries) {
+    for (const name of [...ARTICLE_SKILLS, ...retired]) {
+      const filename = path.join(discovery, name);
+      try {
+        const linked = path.resolve(discovery, await readlink(filename));
+        const targets = [await canonical(linked), path.join(await canonical(path.dirname(linked)), path.basename(linked))];
+        if (roots.some(root => targets.includes(path.join(root, name)))) removed.push(filename);
+      } catch (error) { if (!['ENOENT', 'EINVAL'].includes(error.code)) throw error; }
+    }
+  }
+  // Discover all ownership first: some clients link through another discovery directory.
+  if (!dryRun) for (const filename of removed) await rm(filename);
+  return removed;
+}
+
+/** Earlier releases linked ~/.rtfm-skills at the managed skills copy. Remove that
+ * link when it points into SupportPages Writer's own data directory; a link to
+ * a separate skills checkout belongs to that checkout and is left alone. */
+export async function retireManagedAnchor({ home, dataDir }) {
+  const anchor = path.join(home, '.rtfm-skills');
+  let target;
+  try { target = path.resolve(home, await readlink(anchor)); }
+  catch (error) { if (['ENOENT', 'EINVAL'].includes(error.code)) return false; throw error; }
+  const within = (root, file) => { const relative = path.relative(root, file); return relative && !relative.startsWith('..') && !path.isAbsolute(relative); };
+  const roots = [path.resolve(dataDir)];
+  try { roots.push(await realpath(dataDir)); } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (!roots.some(root => within(root, target))) return false;
+  await rm(anchor);
+  return true;
+}
+
+const shellQuote = value => "'" + value.replaceAll("'", "'\\''") + "'";
+
+/** Register the engine's trace hook with Claude Code, replacing earlier trace hooks. */
+export async function installTraceHook({ home, env, writeJson, hookCommand }) {
+  const filename = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'settings.json');
+  let settings;
+  try { settings = JSON.parse(await readFile(filename, 'utf8')); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; settings = {}; }
+  const groups = settings.hooks?.PostToolUse ?? [];
+  if (!Array.isArray(groups) || groups.some(group => !Array.isArray(group.hooks))) throw Error('Claude Code PostToolUse settings are invalid. Repair them before installing the article trace hook.');
+  // The engine hook is Node; running it with the installation's own node keeps
+  // it working where Node is not on the user's PATH.
+  const command = hookCommand.map(shellQuote).join(' ');
+  settings.hooks = { ...settings.hooks, PostToolUse: [
+    ...groups.map(group => ({ ...group, hooks: group.hooks.filter(hook => !/trace_hook\.(sh|js)/.test(String(hook.command ?? ''))) })).filter(group => group.hooks.length),
+    { matcher: '*', hooks: [{ type: 'command', command }] },
+  ] };
+  await writeJson(filename, settings);
+}
+
+/** Connect the bundled article engine to the chosen clients. The engine's
+ * dependencies live in the package's own node_modules, so nothing is installed
+ * into the skill folders and no skills are exposed to public discovery. */
+export async function installArticleSkills({ home, client, directory, previousDirectory, writeJson, env = {}, dataDir, hookCommand }) {
+  const clients = client === 'both' ? ['claude', 'codex'] : [client === 'manual' ? 'codex' : client];
+  // Retire links before the anchor, so previous installations remain identifiable.
+  const removed = await retirePublicSkillLinks({ home, clients, directory, previousDirectory, env });
+  if (dataDir) await retireManagedAnchor({ home, dataDir });
+  if (clients.includes('claude') && hookCommand) await installTraceHook({ home, env, writeJson, hookCommand });
+  return removed;
+}