@supportpages.io/wtfm 0.0.0-stage → 0.3.0

package/scripts/lib/planning.mjs

@@ -0,0 +1,263 @@
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { readFile, rm } from 'node:fs/promises';
+import { LocalSetup, cacheFiles, projectCacheFiles } from '../../dist/local-setup.js';
+import { fail, publicError } from '../../dist/errors.js';
+import { runAgent, openAgent } from './agent-runner.mjs';
+import { ensureWriterAvailable } from './writer-recovery.mjs';
+import { Cancelled } from './terminal.mjs';
+import { availableAgents, readAgentSettings, executionSettings, modelDescription } from './agent-settings.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+const clean = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, '');
+const label = agent => agent === 'claude' ? 'Claude Code' : 'Codex';
+
+export class Planning {
+  constructor(session, options, deps, clients = []) {
+    this.session = session; this.options = options; this.deps = deps; this.ui = deps.ui; this.clients = clients;
+  }
+  async initialize() {
+    this.bridge = await this.session.bridge();
+    this.store = new LocalSetup(this.bridge.ws, this.bridge.stateRoot);
+    this.destination = await this.bridge.destination();
+    if (this.destination === 'none') fail('project_required', `Run ${CLI_NAME} init to set up this folder first.`);
+    this.projectId = this.destination === 'hosted' ? (await this.bridge.binding()).project_id : undefined;
+    return this;
+  }
+  /** Remote project context, or the folder's own context when it saves articles locally. */
+  projectContext() { return this.bridge.contextFor(this.destination); }
+  async chooseAgent() {
+    if (this.agent) return this.agent;
+    const settingsFile = `${this.bridge.stateRoot}/setup/settings.json`;
+    const saved = await readAgentSettings(this.bridge);
+    const available = await availableAgents(this.session, this.deps, this.clients);
+    const preferred = this.options.agent ?? saved.agent;
+    if (this.options.agent && !available.includes(this.options.agent)) fail('agent_unavailable', `The selected coding agent is not installed and connected. Run ${CLI_NAME} init.`);
+    this.agent = available.includes(preferred) ? preferred : available.length === 1 ? available[0] : await this.ui.choose('Which agent should analyse and plan this project?', available.map(value => ({ value, label: label(value) })));
+    await this.bridge.ws.writeJson(settingsFile, { ...saved, agent: this.agent });
+    return this.agent;
+  }
+  /**
+   * Explain the analysis, then run it now or later. With one agent this is a yes/no
+   * question; with both, the answer also picks the agent (Claude Code first).
+   * Returns the agent to run with, or undefined to defer.
+   */
+  async analysisAgent() {
+    const saved = await readAgentSettings(this.bridge);
+    const connected = await availableAgents(this.session, this.deps, this.clients);
+    if (this.options.agent && !connected.includes(this.options.agent)) fail('agent_unavailable', `The selected coding agent is not installed and connected. Run ${CLI_NAME} init.`);
+    const available = this.options.agent ? [this.options.agent] : connected;
+    const models = await Promise.all(available.map(async agent => modelDescription(agent, await executionSettings(this.bridge, agent))));
+    this.ui.note?.(`SupportPages Writer reads this project once to map its screens, styles and branding, and writes a short product summary. Every article starts from it.\nIt runs in your coding agent with your existing account and takes about 5 minutes.\n\n${models.join('\n')}`, 'Project analysis');
+    let agent;
+    if (available.length === 1) {
+      if (!await this.ui.confirm(`Run the analysis now with ${label(available[0])}?`, true)) return;
+      agent = available[0];
+    } else {
+      const ordered = [...available].sort((a, b) => (b === 'claude') - (a === 'claude'));
+      agent = await this.ui.choose('Run the analysis now?', [
+        ...ordered.map(value => ({ value, label: `Yes, with ${label(value)}`, ...(value === 'claude' ? { hint: 'Recommended' } : {}) })),
+        { value: 'later', label: 'Later', hint: `Run ${CLI_NAME} analyse when you are ready` },
+      ], Math.max(0, ordered.indexOf(saved.agent)));
+      if (agent === 'later') return;
+    }
+    this.agent = agent;
+    await this.bridge.ws.writeJson(`${this.bridge.stateRoot}/setup/settings.json`, { ...saved, agent });
+    return agent;
+  }
+  async context() {
+    const remote = await this.projectContext();
+    if (remote.inventory_truncated) fail('inventory_truncated', 'The help-centre inventory is too large for a complete local planning pass.');
+    const analysis = await this.store.requireAnalysis();
+    return { ...remote, ...remote.product_context, user_context: remote.product_context ?? {}, project_name: remote.project.name,
+      project_overview: analysis.overview, analysis_summary: analysis.summary };
+  }
+
+  async task(skill, context, extra = '') {
+    const agent = await this.chooseAgent();
+    const settings = await executionSettings(this.bridge, agent);
+    const ws = this.bridge.ws;
+    const directory = `${this.bridge.stateRoot}/setup/tasks/${randomUUID()}`;
+    const contextPath = await ws.writeJson(`${directory}/context.json`, context);
+    const output = await ws.resolve(directory);
+    const previous = await this.store.analysis();
+    if (previous.status === 'ready' && await ws.exists(`${previous.output_dir}/file_tree.txt`)) await ws.write(`${directory}/file_tree.txt`, await ws.read(`${previous.output_dir}/file_tree.txt`));
+    let instructions;
+    try { instructions = await readFile(path.join(this.session.options.skillsDir, skill, 'SKILL.md'), 'utf8'); }
+    catch { fail('missing_dependency', `The ${skill} skill is missing. Run ${CLI_NAME} init to repair the installation.`); }
+    const receipt = { version: 1, skill, agent, workspace: ws.root, output_dir: directory, status: 'running', started_at: new Date().toISOString() };
+    this.activeTask = receipt;
+    await ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, receipt);
+    const targetContract = skill === 'detect-project' ? `\n\nLocal setup output contract: Write ${output}/analysis-target.json containing {"codebase_dir":"."} when analysing the workspace root, or the actual workspace-relative application directory (for example {"codebase_dir":"apps/web"}) when analysing a nested application. Keep branding.json, project_map.json and branding.css in that application's .rtfm directory. Do not copy its cache into the parent: source paths are relative to the application. Write summary.md and overview.txt in ${output}. Before reporting success, verify all five files exist and contain valid output, including when reusing an existing cache. Record the selected directory even when invoking the skill through the Skill tool.` : '';
+    const prompt = `Run the ${skill} skill for this local project. Complete the task and write its output files; do not generate articles, publish, or call SupportPages.io MCP tools.\nIf a required tool or file access needs permission, stop and report the block. Do not work around permission denials by copying scripts or switching tools.\nWorkspace: ${ws.root}\nEngine root: ${this.session.options.skillsDir} (exported as RTFM_SKILLS_DIR, which the skill paths use).\nContext: ${contextPath}\nOutput directory: ${output}\n${extra}\n\n${instructions}${targetContract}`;
+    const env = { ...this.deps.env, RTFM_WORKSPACE: ws.root, RTFM_CONTEXT_FILE: contextPath, RTFM_OUTPUT_DIR: output,
+      RTFM_ANALYZE: skill === 'detect-project' ? 'full' : '', RTFM_SKILLS_DIR: this.session.options.skillsDir };
+    try {
+      await (this.deps.runAgent ?? runAgent)({ agent, ...settings, workspace: ws.root, prompt, ui: this.ui,
+        env,
+        logPath: await ws.resolve(`${directory}/agent.log`) });
+      return { directory, receipt };
+    } catch (error) {
+      await ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, { ...receipt, status: error instanceof Cancelled ? 'cancelled' : 'failed', error: publicError(error), finished_at: new Date().toISOString() });
+      if (['agent_failed', 'agent_unavailable', 'agent_timeout', 'agent_permission_required'].includes(error.code)) {
+        this.ui.line(publicError(error).message);
+        const action = await this.ui.choose('Continue this setup stage?', [
+          { value: 'interactive', label: `Open ${label(agent)} to finish interactively`, hint: 'Sign in or approve tools in your agent, then exit when finished.' },
+          { value: 'stop', label: 'Stop and retry later' }]);
+        if (action === 'interactive') {
+          await ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, receipt);
+          if (await (this.deps.openAgent ?? openAgent)({ agent, ...settings, workspace: ws.root, prompt, env, ui: this.ui })) {
+            // The caller still validates every output; exiting the agent is not success.
+            return { directory, receipt };
+          }
+        }
+      }
+      await ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, { ...receipt, status: error instanceof Cancelled ? 'cancelled' : 'failed', error: publicError(error), finished_at: new Date().toISOString() });
+      throw error;
+    }
+  }
+  async finish(task) {
+    await this.bridge.ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, { ...task.receipt, status: 'completed', finished_at: new Date().toISOString() });
+    this.activeTask = undefined;
+  }
+  async failedTask(error) {
+    if (!this.activeTask) return;
+    await this.bridge.ws.writeJson(`${this.bridge.stateRoot}/setup/task.json`, { ...this.activeTask,
+      status: error instanceof Cancelled ? 'cancelled' : 'failed', error: publicError(error), finished_at: new Date().toISOString() });
+    this.activeTask = undefined;
+  }
+  async sourceCommit(codebaseDir = '.') {
+    const result = await this.deps.run('git', ['rev-parse', 'HEAD'], { cwd: await this.bridge.ws.resolve(codebaseDir), capture: true });
+    return result.code === 0 && /^[a-f0-9]{40,64}$/.test(result.stdout?.trim() ?? '') ? result.stdout.trim() : null;
+  }
+  async recoverAnalysis() {
+    const ws = this.bridge.ws;
+    const file = `${this.bridge.stateRoot}/setup/task.json`;
+    if (!await ws.exists(file)) return;
+    const task = await ws.json(file);
+    if (task.skill !== 'detect-project' || task.status !== 'failed' || task.workspace !== ws.root || typeof task.output_dir !== 'string') return;
+    if (!task.output_dir.startsWith(`${this.bridge.stateRoot}/setup/tasks/`)) return;
+    const candidates = [];
+    try { candidates.push((await this.store.validate(task.output_dir)).codebase_dir); }
+    catch {
+      // Legacy runs did not record their chosen application. Offer only complete
+      // immediate-child caches, then let the user identify the intended product.
+      if (await ws.exists(`${task.output_dir}/analysis-target.json`)) return;
+      for (const entry of (await ws.list('.')).slice(0, 200)) {
+        if (!entry.isDirectory() || entry.name.startsWith('.') || ['node_modules', 'vendor', 'output'].includes(entry.name)) continue;
+        try { await this.store.validate(task.output_dir, entry.name); candidates.push(entry.name); } catch { /* Incomplete or unsafe cache. */ }
+      }
+    }
+    if (!candidates.length) return;
+    this.ui.note?.((await ws.read(`${task.output_dir}/overview.txt`)).toString(), 'Previous analysis');
+    const selected = candidates.length === 1
+      ? await this.ui.confirm(`Reuse the completed analysis for ${clean(candidates[0])}?`, true) ? candidates[0] : undefined
+      : await this.ui.choose('Which application was analysed?', [...candidates.map(value => ({ value, label: clean(value) })), { value: '', label: 'Run analysis again' }]);
+    if (!selected) return;
+    await this.store.accept(task.output_dir, task.agent, await this.bridge.version(), await this.sourceCommit(selected), selected);
+    await this.finish({ receipt: task });
+    this.ui.ok(`Recovered project analysis from ${clean(selected)}.`);
+    return this.store.requireAnalysis();
+  }
+  async analyse(refresh = false, hint = this.options['app-type'], correction = '') {
+    const ws = this.bridge.ws;
+    let result, previousReady = false;
+    for (;;) {
+      try {
+        await ws.lock(async () => {
+          const existing = await this.store.analysis();
+          previousReady = existing.status === 'ready';
+          // Detection that stopped short names the app type it needs; use it rather
+          // than making the user repeat what the map already asked for.
+          if (!hint && !previousReady && existing.app_type) {
+            hint = existing.app_type;
+            this.ui.line(`The saved project map is incomplete and asks for app_type=${hint}. Detecting again with that app type.`);
+          }
+          const commit = await this.sourceCommit(existing.status === 'ready' ? existing.codebase_dir : '.');
+          if (existing.status === 'ready' && !refresh && commit && existing.source_commit && existing.source_commit !== commit) {
+            refresh = await this.ui.confirm('This checkout has changed since analysis. Refresh it now?', false);
+          }
+          if (existing.status === 'ready' && !refresh) {
+            // Say which analysis is in use and how to redo it, so a stale cache is
+            // never a silent surprise.
+            this.ui.line(`Using the project analysis from ${clean(existing.completed_at?.slice(0, 10) ?? 'an earlier run')}. Rerun with ${CLI_NAME} ${this.options.command === 'init' ? 'init' : 'analyse'} --refresh to redo it.`);
+            result = existing;
+            return;
+          }
+          await this.bridge.runs.assertAvailable();
+          if (!refresh) { result = await this.recoverAnalysis(); if (result) return; }
+          if (!refresh && await ws.exists('output/detect-project/summary.md')) {
+            try { await this.store.accept('output/detect-project', 'existing cache', await this.bridge.version()); result = await this.store.requireAnalysis(); return; }
+            catch { /* Incomplete legacy detection needs a full run. */ }
+          }
+          if (!await this.analysisAgent()) return;
+          this.ui.info?.('Loading project context…');
+          const backup = new Map();
+          const restoreFiles = [...new Set([...cacheFiles, ...(existing.status === 'ready' ? projectCacheFiles(existing.codebase_dir) : []), `${this.bridge.stateRoot}/setup/analysis.json`])];
+          for (const file of restoreFiles) if (await ws.exists(file)) backup.set(file, await ws.read(file, 10 * 1024 * 1024));
+          let task, validation;
+          try {
+            const context = await this.projectContext();
+            task = await this.task('detect-project', { ...context, ...context.product_context, project_name: context.project.name }, `RTFM_ANALYZE=full: summary.md and overview.txt are mandatory. ${hint ? `Explicit app_type=${hint}.` : ''} ${correction ? `User correction: ${correction}` : ''}`);
+            validation = this.ui.progress?.('Checking analysis files…');
+            const target = await this.store.validate(task.directory);
+            await this.store.accept(task.directory, this.agent, await this.bridge.version(), await this.sourceCommit(target.codebase_dir), target.codebase_dir);
+            await this.finish(task);
+            result = await this.store.requireAnalysis();
+            validation?.stop('Analysis files checked and saved.');
+          } catch (error) {
+            validation?.stop('Analysis files could not be validated.', 'error');
+            for (const file of restoreFiles) {
+              if (backup.has(file)) await ws.write(file, backup.get(file));
+              else await rm(await ws.resolve(file), { force: true });
+            }
+            await this.failedTask(error);
+            if (task && error.code === 'missing_artifact') fail('invalid_analysis', `Project analysis did not produce all required files: ${publicError(error).message}. The summary and agent log are saved in ${task.directory}. Rerun ${CLI_NAME} init to recover a completed nested-application analysis or try again.`, { output_dir: task.directory });
+            if (error instanceof Cancelled || error.code) throw error;
+            fail('invalid_analysis', `The analysis is incomplete or invalid. Run ${CLI_NAME} analyse --refresh to retry; the previous valid cache was kept.`);
+          }
+        });
+        break;
+      } catch (error) {
+        if (error.code !== 'generation_active') throw error;
+        await ensureWriterAvailable(this.bridge, this.ui);
+      }
+    }
+    if (!result) {
+      this.ui.outro?.(previousReady
+        ? `Refresh deferred. Your previous analysis is still ready. Run ${CLI_NAME} analyse --refresh when you want to update it.`
+        : `Analysis deferred. Your project settings are saved.\nRun ${CLI_NAME} analyse when you are ready; articles need it first.`);
+      return;
+    }
+    this.ui.note?.(`${clean(result.overview)}\n\nApplication: ${clean(result.codebase_dir)}\nApp type: ${clean(result.app_type)}\nFramework: ${clean(result.framework)}`, 'Project analysis');
+    this.ui.ok('Project analysis is ready.');
+    return result;
+  }
+  async reviewAnalysis() {
+    return Boolean(await this.analyse(Boolean(this.options.refresh || this.options['app-type'])));
+  }
+  async write() {
+    await this.store.requireAnalysis();
+    await ensureWriterAvailable(this.bridge, this.ui);
+    const agent = await this.chooseAgent();
+    const connection = this.session.options.dev ? 'supportpages-dev' : 'supportpages';
+    const other = this.session.options.dev ? 'supportpages' : 'supportpages-dev';
+    let disabledConnection = agent === 'claude' ? other : undefined;
+    if (agent === 'codex') {
+      // An enabled-only entry for a missing server is invalid Codex config.
+      const existing = await this.deps.run('codex', ['mcp', 'get', other, '--json'], { cwd: this.bridge.ws.root, capture: true });
+      if (existing.code === 0 && existing.stdout?.trim()) disabledConnection = other;
+    }
+    const prompt = this.destination === 'local'
+      ? `Use the ${connection} MCP connection for this project (${this.session.options.origin}). Project detection is complete. This project saves articles locally as Markdown and screenshots; there is no help centre and no sign-in is needed. Ask me which single article I want to write, then create it using SupportPages.io: call supportpages_prepare_article before writing and supportpages_complete_article after successful generation, then show where the article was saved. Do not upload, publish or start sign-in automatically. If I explicitly ask to host the saved articles, use supportpages_publish. Do not run the retired planning skills (suggest-sections, recommend-articles); running detect-project again is allowed and required when the project map is missing, stale or reports an incomplete detection.`
+      : `Use the ${connection} MCP connection for this project (${this.session.options.origin}). Project detection is complete. Ask me which single article I want to write, then create it using SupportPages.io. Use supportpages_prepare_article before writing and supportpages_complete_article after successful generation. Return the draft review link. Do not publish automatically. Sections, topic suggestions and PR analysis are available in the web app after connecting a repository, so do not run the retired planning skills (suggest-sections, recommend-articles). Running detect-project again is allowed and required when the project map is missing, stale or reports an incomplete detection.`;
+    this.ui.outro?.(`Opening ${label(agent)} in this project.`);
+    return (this.deps.openAgent ?? openAgent)({ agent, ...await executionSettings(this.bridge, agent), workspace: this.bridge.ws.root, prompt, env: this.deps.env, ui: this.ui, disabledConnection });
+  }
+  async menu() {
+    await ensureWriterAvailable(this.bridge, this.ui);
+    this.ui.ok('Ready to write.');
+    const agent = await this.chooseAgent();
+    this.ui.outro?.(`Open ${label(agent)} in this project and ask for an article, for example: “Write an illustrated guide to inviting a teammate.” Restart ${label(agent)} first if it was already open.`);
+  }
+}

package/scripts/lib/prepare-update.mjs

@@ -0,0 +1,85 @@
+import path from 'node:path';
+import os from 'node:os';
+import { chmod, copyFile, lstat, readFile, realpath, rename, rm } from 'node:fs/promises';
+import { ARTICLE_SKILLS, installTraceHook } from './article-skills.mjs';
+import { command, exists, privateJson } from './install.mjs';
+import { ensureRenderer, rendererReady } from './renderer.mjs';
+import { refreshCodexSkill } from './codex-skill.mjs';
+import { refreshWriters } from './refresh-writers.mjs';
+
+/** Did the previous release ever render? Releases with an engine count when
+ * their Chromium is on disk; earlier releases installed renderer dependencies
+ * into skills/<name>/node_modules. Unused installations download nothing. */
+async function rendererUsed(previous, home, run) {
+  if (await exists(path.join(previous, 'engine'))) {
+    const node = path.resolve(previous, '../runtime/bin/node');
+    if (await rendererReady(path.join(previous, 'engine'), run, await exists(node) ? node : process.execPath)) return true;
+  }
+  const roots = [path.join(previous, 'skills')];
+  // A local CLI build may have used an older release's skills through the
+  // managed ~/.rtfm-skills shortcut.
+  try { roots.push(await realpath(path.join(home, '.rtfm-skills'))); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  for (const root of roots) for (const skill of ARTICLE_SKILLS) if (await exists(path.join(root, skill, 'node_modules'))) return true;
+  return false;
+}
+
+/** Point an existing SupportPages trace hook at this installation's Node hook,
+ * through the managed `current` link so it survives later updates. Clients
+ * that never had the hook are left alone. */
+async function migrateTraceHook(root, { home, env }) {
+  const settingsFile = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'), 'settings.json');
+  let settings;
+  try { settings = JSON.parse(await readFile(settingsFile, 'utf8')); } catch { return; }
+  const managed = [path.join(home, '.rtfm-skills'), root];
+  const hooks = (settings.hooks?.PostToolUse ?? []).flatMap(group => Array.isArray(group.hooks) ? group.hooks : []);
+  if (!hooks.some(hook => /trace_hook\.(sh|js)/.test(String(hook.command ?? '')) && managed.some(prefix => String(hook.command).includes(prefix)))) return;
+  const current = path.join(root, 'current');
+  await installTraceHook({ home, env, writeJson: privateJson, hookCommand: [
+    path.join(current, 'runtime', 'bin', 'node'),
+    path.join(current, 'mcp', 'engine', 'generate-illustrated-article', 'scripts', 'trace_hook.js'),
+  ] });
+}
+
+const MANAGED_LAUNCHER = '# SupportPages managed launcher';
+async function managedLauncher(file) {
+  try {
+    if (!(await lstat(file)).isFile()) return false;
+    return (await readFile(file, 'utf8')).split('\n')[1] === MANAGED_LAUNCHER;
+  } catch { return false; }
+}
+
+/** Updates run the previous release's installer, which only writes the
+ * `supportpages` launcher. Add the identical `wtfm` launcher beside it so an
+ * existing installation gains the new command name. Best effort: anything
+ * unexpected (no receipt, an unrelated wtfm) leaves the installation as it is. */
+export async function ensureCommandAlias(root) {
+  try {
+    const receipt = JSON.parse(await readFile(path.join(root, 'install.json'), 'utf8'));
+    if (typeof receipt.bin_dir !== 'string' || !path.isAbsolute(receipt.bin_dir)) return false;
+    const existing = path.join(receipt.bin_dir, 'supportpages'), alias = path.join(receipt.bin_dir, 'wtfm');
+    if (!await managedLauncher(existing)) return false;
+    try { await lstat(alias); return false; } catch (error) { if (error.code !== 'ENOENT') return false; }
+    const temporary = path.join(receipt.bin_dir, `.wtfm.${process.pid}.${Date.now()}`);
+    try {
+      await copyFile(existing, temporary);
+      await chmod(temporary, 0o755);
+      await rename(temporary, alias);
+    } finally { await rm(temporary, { force: true }); }
+    return true;
+  } catch { return false; }
+}
+
+/** Prepare the new release's renderer and hook before promoting it, then
+ * refresh managed writer and coordination instructions. */
+export async function prepareUpdate(previous, next, { run = command, env = process.env, home = os.homedir() } = {}) {
+  const engine = path.join(next, 'engine');
+  if (await exists(engine) && await rendererUsed(previous, home, run)) {
+    const node = path.resolve(next, '../runtime/bin/node');
+    if (!await ensureRenderer(engine, run, { node })) throw Error('Could not prepare the updated article renderer. The current release is still active.');
+  }
+  if (await exists(engine)) await migrateTraceHook(path.resolve(next, '../../..'), { home, env });
+  await refreshWriters({ home, env });
+  await refreshCodexSkill({ home, env });
+  await ensureCommandAlias(path.resolve(next, '../../..'));
+}

package/scripts/lib/refresh-writers.mjs

@@ -0,0 +1,12 @@
+import path from 'node:path';
+import os from 'node:os';
+import { installManagedWriter } from './managed-writer.mjs';
+
+/** Update owned writer policies without adding integrations or changing permissions. */
+export async function refreshWriters({ home = os.homedir(), env = process.env } = {}) {
+  const { codexWriterFile, writerAgentFile, writerAgentType } = await import('../../dist/writer-agent.js');
+  for (const entry of [
+    { config: path.resolve(env.CODEX_HOME || path.join(home, '.codex')), extension: 'toml', contents: codexWriterFile, marker: '# Managed by SupportPages: article writer v1' },
+    { config: path.resolve(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude')), extension: 'md', contents: writerAgentFile, marker: '<!-- Managed by SupportPages: article writer v1 -->' },
+  ]) await installManagedWriter({ ...entry, name: writerAgentType, existingOnly: true });
+}

package/scripts/lib/remove.mjs

@@ -0,0 +1,167 @@
+import os from 'node:os';
+import path from 'node:path';
+import { lstat, readFile, readdir, realpath, rm } from 'node:fs/promises';
+import { backup, expand, privateJson } from './install.mjs';
+import { retirePublicSkillLinks } from './article-skills.mjs';
+import { Cancelled } from './terminal.mjs';
+import { fail } from '../../dist/errors.js';
+import { claudePermissionRules } from './claude-permissions.mjs';
+import { CLI_NAME } from './brand.mjs';
+
+const clean = value => String(value).replace(/[\p{Cc}\p{Cf}]/gu, '');
+const object = value => value && typeof value === 'object' && !Array.isArray(value);
+const canonical = async filename => { try { return await realpath(filename); } catch { return path.resolve(filename); } };
+
+/** Remove local integrations only; never contact the API or change a product workspace. */
+export async function removeIntegration(options, { home = os.homedir(), env = process.env, ui, run }) {
+  const configDir = expand(options['config-dir'] ?? path.join(env.XDG_CONFIG_HOME || path.join(home, '.config'), 'supportpages'));
+  const directory = path.join(configDir, 'installations');
+  const clients = options.agent ? [options.agent] : ['claude', 'codex'];
+  const claudeDir = path.resolve(env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'));
+  const claudeFile = env.CLAUDE_CONFIG_DIR ? path.join(claudeDir, '.claude.json') : path.join(home, '.claude.json');
+  const codexDir = path.resolve(env.CODEX_HOME || path.join(home, '.codex'));
+  const snapshots = new Map(), edits = new Map(), removals = [], commands = [], descriptions = [];
+  async function read(filename) {
+    if (snapshots.has(filename)) return snapshots.get(filename);
+    // Refuse linked configuration paths, including linked parent directories.
+    const base = [configDir, claudeDir, codexDir, home].sort((a, b) => b.length - a.length).find(root => filename.startsWith(root + path.sep)) ?? path.dirname(filename);
+    for (let cursor = filename; cursor !== path.dirname(base) && cursor !== path.dirname(cursor); cursor = path.dirname(cursor)) {
+      try { if ((await lstat(cursor)).isSymbolicLink()) fail('unsafe_configuration', `Keep the linked configuration path: ${clean(cursor)}`); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    let contents;
+    try { contents = await readFile(filename, 'utf8'); }
+    catch (error) { if (error.code !== 'ENOENT') throw error; contents = null; }
+    snapshots.set(filename, contents);
+    return contents;
+  }
+  async function json(filename) {
+    const contents = await read(filename);
+    if (contents === null) return null;
+    try { const value = JSON.parse(contents); if (object(value)) return value; } catch { /* Safe error without configuration contents. */ }
+    fail('invalid_configuration', `Cannot read the configuration at ${clean(filename)}. Repair it before removing the integration.`);
+  }
+  async function matches(actual, expected) {
+    return actual && expected && Array.isArray(actual.args) && Array.isArray(expected.args) &&
+      JSON.stringify(actual.args) === JSON.stringify(expected.args) && typeof actual.command === 'string' && typeof expected.command === 'string' &&
+      await canonical(actual.command) === await canonical(expected.command);
+  }
+  let filenames;
+  try { filenames = await readdir(directory); } catch (error) { if (error.code !== 'ENOENT') throw error; filenames = []; }
+  const records = [];
+  for (const filename of filenames.sort()) {
+    if (!/^[a-z0-9][a-z0-9_-]{0,79}\.json$/.test(filename)) continue;
+    const receiptPath = path.join(directory, filename);
+    const receipt = await json(receiptPath);
+    if (![1, 2].includes(receipt?.version) || receipt.name !== filename.slice(0, -5) || !Array.isArray(receipt.clients) || receipt.clients.some(client => !['claude', 'codex'].includes(client))) continue;
+    const manualPath = path.join(directory, `${receipt.name}.mcp.json`);
+    const manual = await json(manualPath);
+    const expected = manual?.mcpServers?.[receipt.name];
+    const selected = (!options.dev || expected?.args?.includes('--dev') || receipt.name === 'supportpages-dev') &&
+      (!options['api-url'] || receipt.api_origin === options['api-url']);
+    records.push({ receipt, receiptPath, manualPath, expected, selected, remaining: [...receipt.clients] });
+  }
+  let claude, settings;
+  const rules = new Set();
+  if (!options['skills-only']) {
+    for (const record of records.filter(record => record.selected)) {
+      const { receipt, expected } = record;
+      for (const client of receipt.clients.filter(client => clients.includes(client))) {
+        let actual;
+        if (client === 'claude') {
+          claude ??= await json(claudeFile) ?? {};
+          if (claude.mcpServers !== undefined && !object(claude.mcpServers)) fail('invalid_configuration', 'Claude MCP settings are invalid. Repair them before removal.');
+          actual = claude.mcpServers?.[receipt.name];
+        } else {
+          const filename = path.join(codexDir, 'config.toml');
+          if (await read(filename) !== null) {
+            const result = await run('codex', ['mcp', 'get', receipt.name, '--json'], { capture: true, env: { ...env, CODEX_HOME: codexDir } });
+            if (result.code === 0) {
+              try { const value = JSON.parse(result.stdout); actual = value.transport ?? value; }
+              catch { fail('invalid_configuration', 'Codex returned invalid MCP configuration. No integrations were removed.'); }
+            } else if (result.code !== 1 || !/No MCP server .*found/i.test(result.stderr ?? '')) {
+              fail('client_unavailable', 'Could not inspect Codex. Restore its command, or use --agent claude to remove only Claude integration.');
+            }
+          }
+        }
+        if (actual && !await matches(actual, expected)) {
+          ui.line(`Kept changed or unmanaged ${client} connection: ${clean(receipt.name)}`);
+          continue;
+        }
+        if (actual) {
+          descriptions.push(`${client === 'claude' ? 'Claude Code' : 'Codex'} connection: ${receipt.name}`);
+          if (client === 'claude') { delete claude.mcpServers[receipt.name]; edits.set(claudeFile, claude); }
+          else commands.push({ name: receipt.name, filename: path.join(codexDir, 'config.toml') });
+        }
+        if (client === 'claude') {
+          // Older setups added only the publish rule; current ones allow the server and ask for removals.
+          const current = claudePermissionRules(receipt.name);
+          for (const rule of [`mcp__${receipt.name}__supportpages_publish_article`, ...current.allow, ...current.ask]) rules.add(rule);
+        }
+        record.remaining = record.remaining.filter(value => value !== client);
+      }
+      if (!record.remaining.length && (!options.agent || record.receipt.clients.includes(options.agent))) {
+        removals.push(record.receiptPath, record.manualPath);
+        descriptions.push(`Saved integration registration: ${record.receipt.name}`);
+      } else if (record.remaining.length !== record.receipt.clients.length) edits.set(record.receiptPath, { ...record.receipt, clients: record.remaining });
+    }
+    for (const client of clients) {
+      // Writer definitions and the trace hook are shared by all API connections.
+      if (records.some(record => record.remaining.includes(client)) ||
+          (options.dev || options['api-url']) && !records.some(record => record.selected && record.receipt.clients.includes(client))) continue;
+      const filename = path.join(client === 'claude' ? claudeDir : codexDir, 'agents', `supportpages-io.${client === 'claude' ? 'md' : 'toml'}`);
+      const contents = await read(filename);
+      const marker = client === 'claude' ? '<!-- Managed by SupportPages: article writer v1 -->' : '# Managed by SupportPages: article writer v1';
+      if (contents?.includes(marker)) { removals.push(filename); descriptions.push(`${client === 'claude' ? 'Claude Code' : 'Codex'} SupportPages Writer agent`); }
+    }
+    if (clients.includes('claude')) {
+      const filename = path.join(claudeDir, 'settings.json');
+      settings = await json(filename);
+      if (settings) {
+        const before = JSON.stringify(settings);
+        for (const key of ['allow', 'ask']) {
+          if (Array.isArray(settings.permissions?.[key])) settings.permissions[key] = settings.permissions[key].filter(rule => !rules.has(rule));
+        }
+        if ((!options.dev && !options['api-url'] || records.some(record => record.selected && record.receipt.clients.includes('claude'))) && !records.some(record => record.remaining.includes('claude')) && Array.isArray(settings.hooks?.PostToolUse)) {
+          const skillDirs = records.map(record => record.receipt.skills_dir).filter(value => typeof value === 'string');
+          // Hooks name the engine by its managed `current` path so they survive updates.
+          const stable = skillDirs.map(dir => dir.replace(/\/versions\/[^/]+\/mcp\/(skills|engine)$/, '/current/mcp/$1'));
+          const roots = [path.join(home, '.rtfm-skills'), ...skillDirs, ...stable];
+          const ours = command => roots.some(root => ['sh', 'js'].some(ext => String(command ?? '').includes(path.join(root, `generate-illustrated-article/scripts/trace_hook.${ext}`))));
+          settings.hooks.PostToolUse = settings.hooks.PostToolUse.map(group => Array.isArray(group.hooks)
+            ? { ...group, hooks: group.hooks.filter(item => !ours(item.command)) } : group)
+            .filter(group => !Array.isArray(group.hooks) || group.hooks.length);
+        }
+        if (JSON.stringify(settings) !== before) { edits.set(filename, settings); descriptions.push('SupportPages.io Claude permissions and unused trace hook'); }
+      }
+    }
+  }
+  const skillOptions = records.filter(record => record.selected).map(record => ({ home, env, clients: options.agent ? clients : [...new Set([...record.receipt.clients, 'codex', 'claude'])],
+    directory: record.receipt.skills_dir ?? record.expected?.args?.[record.expected.args.indexOf('--skills-dir') + 1] }));
+  if (!options.dev && !options['api-url']) skillOptions.push({ home, env, clients, directory: expand(options['skills-dir'] ?? env.RTFM_SKILLS_DIR ?? path.join(home, '.rtfm-skills')) });
+  const links = new Set();
+  for (const args of skillOptions) for (const filename of await retirePublicSkillLinks({ ...args, dryRun: true })) links.add(filename);
+  descriptions.push(...[...links].map(filename => `Skill shortcut: ${filename}`));
+  if (!descriptions.length && !edits.size) { ui.ok('No managed SupportPages Writer integration found to remove.'); return { status: 'unchanged' }; }
+  ui.intro?.('SupportPages Writer · Remove integration');
+  for (const description of descriptions) ui.line(clean(description));
+  ui.line('Projects, article files, saved repository links, downloaded engines, saved credentials and SupportPages Writer will be kept.');
+  if (!options.yes && !await ui.confirm(options['skills-only'] ? 'Remove these SupportPages.io skill shortcuts?' : 'Remove these SupportPages Writer integrations?', false)) throw new Cancelled('Removal cancelled. Your integration was kept.');
+  // Do not overwrite edits made while the user reviewed the removal list.
+  for (const [filename, before] of snapshots) {
+    let current;
+    try { current = await readFile(filename, 'utf8'); } catch (error) { if (error.code !== 'ENOENT') throw error; current = null; }
+    if (current !== before) fail('configuration_changed', `Configuration changed during review. Rerun ${CLI_NAME} remove to review it again.`);
+  }
+  for (const item of commands) {
+    await backup(item.filename, path.join(configDir, 'backups'));
+    const result = await run('codex', ['mcp', 'remove', item.name], { capture: true, env: { ...env, CODEX_HOME: codexDir } });
+    if (result.code !== 0) fail('remove_failed', `Codex could not remove ${item.name}. Its installation receipt was kept; rerun ${CLI_NAME} remove to finish.`);
+  }
+  for (const [filename, value] of edits) { await backup(filename, path.join(configDir, 'backups')); await privateJson(filename, value); }
+  for (const args of skillOptions) await retirePublicSkillLinks(args);
+  for (const filename of removals) { await backup(filename, path.join(configDir, 'backups')); await rm(filename, { force: true }); }
+  ui.ok(options['skills-only'] ? 'SupportPages.io skill shortcuts removed.' : 'SupportPages Writer integrations removed.');
+  ui.line('Restart existing coding-agent sessions to unload the removed integrations and cached skills.');
+  return { status: 'removed' };
+}

package/scripts/lib/renderer.mjs

@@ -0,0 +1,34 @@
+import path from 'node:path';
+
+// The engine's renderer resolves puppeteer from the package's node_modules.
+// Plugin installs run npm without lifecycle scripts, so puppeteer's own
+// Chromium download may never have happened: run it here instead.
+const resolvePuppeteer = articleDir => [
+  '--input-type=module', '-e',
+  "import {createRequire} from 'node:module'; const require=createRequire(process.argv[1]+'/package.json'); process.stdout.write(require.resolve('puppeteer/package.json'));",
+  articleDir,
+];
+const checkBrowser = articleDir => [
+  '--input-type=module', '-e',
+  "import {createRequire} from 'node:module'; import {accessSync} from 'node:fs'; const require=createRequire(process.argv[1]+'/package.json'); const p=require('puppeteer'); accessSync(await p.executablePath());",
+  articleDir,
+];
+
+/** True when puppeteer loads and its Chromium is on disk. */
+export async function rendererReady(skillsDir, run, node = process.execPath) {
+  const articleDir = path.join(skillsDir, 'generate-illustrated-article');
+  return (await run(node, checkBrowser(articleDir), { capture: true })).code === 0;
+}
+
+/** Download puppeteer's pinned Chromium when it is missing. Returns true when ready. */
+export async function ensureRenderer(skillsDir, run, { node = process.execPath, ui } = {}) {
+  if (await rendererReady(skillsDir, run, node)) return true;
+  const articleDir = path.join(skillsDir, 'generate-illustrated-article');
+  const located = await run(node, resolvePuppeteer(articleDir), { capture: true });
+  if (located.code !== 0 || !located.stdout.trim()) return false;
+  ui?.line?.('  Downloading Chromium for article screenshots. This can take a few minutes the first time.');
+  // puppeteer's postinstall script: downloads the pinned browsers into its cache.
+  const installer = path.join(path.dirname(located.stdout.trim()), 'install.mjs');
+  const result = await run(node, [installer], { cwd: path.dirname(installer) });
+  return result.code === 0 && rendererReady(skillsDir, run, node);
+}