mobile-automator 0.30.1 → 0.31.1

package/README.md

@@ -73,6 +73,8 @@ In **Cursor**, `init` installs a project rule instead — just ask the agent in
 
 That's it. Scenarios land in `mobile-automator/scenarios/`, results in `mobile-automator/results/`.
 
+**Upgrading:** after `npm i -g mobile-automator@latest`, re-run `mauto init --agent <host>` in each project to refresh the skills, rules and commands it installed. Until you do, `mauto guide` starts with a notice that the host integration is out of date, and `mauto doctor` reports which hosts need refreshing.
+
 ---
 
 ## 🧠 How it works
@@ -135,6 +137,7 @@ Most low-level verbs are called **by the agent**, not by you. The ones you'll ru
 | Command | What it does |
 |---------|--------------|
 | `mauto init --agent <claude\|cursor\|gemini\|copilot\|agents\|all>` | Install native Agent Skills into each host's skills directory; also writes slash-commands/rules + MCP entry for claude/cursor |
+| `mauto doctor` | Report whether the integration `init` installed is missing or out of date, and the `init` command that refreshes it |
 | `mauto setup [--mode aware\|agnostic]` | Scaffold the `mobile-automator/` workspace + config |
 | `mauto devices` · `devices use <id>` · `devices clear` | List / pin / unpin the target device |
 | `mauto guide <generate\|execute\|setup>` | Print the workflow guidance for a topic |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mobile-automator",
-  "version": "0.30.1",
+  "version": "0.31.1",
   "description": "Host-agnostic mauto CLI for AI-driven mobile QA automation — analyzes a mobile project and drives devices through mobile-mcp.",
   "homepage": "https://github.com/sh3lan93/mobile-automator#readme",
   "repository": {

package/src/cli.js

@@ -23,6 +23,9 @@ const { validateAt } = require('./config/schema');
 const { scaffold } = require('./setup/scaffold');
 const guideEmitter = require('./guide/emitter');
 const { ADAPTERS } = require('./init/adapters');
+const { inspectHosts, ADVISORY_FS_CODES } = require('./init/host-plan');
+const { renderStaleNotice, installedBefore, refreshHint } = require('./init/stale-notice');
+const { doctorReport } = require('./init/doctor');
 const { isSemanticAction, ACTION_METHOD, selectResolver } = require('./device/semantic-press');
 const connection = require('./device/connection');
 const { isSupportedHost, unsupportedHostError } = require('./device/host-support');
@@ -990,7 +993,20 @@ async function handleTelemetryFlush({ projectRoot, env = process.env, flusher })
 }
 
 // RAW content on success; fail envelope only when the topic is unknown.
-function handleGuide({ projectRoot, emitter = guideEmitter, config = configManager }, topic) {
+//
+// #144: when a host integration `mauto init` wrote is missing or out of date,
+// a notice is prepended. It lives HERE and never inside emitter.emitGuide /
+// emitBootstrap: init embeds emitBootstrap in the cursor rule and the MCP
+// prompts server serves emitGuide, so putting it there would make init's
+// output depend on workspace state (and break byte-identical reruns). The
+// inspection is advisory: a filesystem fault that means "the workspace's
+// integration files can't be read" simply yields no notice, while any other
+// failure escapes to the envelope boundary — a defect in the inspection must
+// be visible, not silently disable the notice forever.
+function handleGuide(
+  { projectRoot, emitter = guideEmitter, config = configManager, inspect = inspectHosts },
+  topic
+) {
   const cfg = config.load(projectRoot);
   const mode = config.resolveMode(cfg);
   let raw;
@@ -1002,6 +1018,14 @@ function handleGuide({ projectRoot, emitter = guideEmitter, config = configManag
       exitKind: 'invalid_input',
     };
   }
+  let stale;
+  try {
+    stale = inspect(projectRoot).filter((h) => h.stale);
+  } catch (err) {
+    if (!(err && ADVISORY_FS_CODES.has(err.code))) throw err;
+    stale = [];
+  }
+  if (stale.length) raw = renderStaleNotice(stale) + raw;
   return { raw, exitKind: 'ok' };
 }
 
@@ -1129,7 +1153,7 @@ function hintForAdapterError(cls) {
 function applyOneAdapter(adapter, agent, projectRoot) {
   try {
     const r = adapter.apply({ projectRoot });
-    return { agent, ok: true, written: r.written, merged: r.merged };
+    return { agent, ok: true, changes: r.changes };
   } catch (err) {
     return {
       agent,
@@ -1140,15 +1164,16 @@ function applyOneAdapter(adapter, agent, projectRoot) {
   }
 }
 
-function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
+function handleInit({ projectRoot, adapters = ADAPTERS, inspect = inspectHosts }, agent) {
   const known = Object.keys(adapters);
   if (agent === 'all') {
+    const wasInstalled = installedBefore(inspect, projectRoot);
     // Continue-on-error: every host is attempted; the result is ONE envelope
     // carrying a per-agent ok/failed map. `ok` only when all succeed.
     const perAgent = known.map((a) => applyOneAdapter(adapters[a], a, projectRoot));
     const failed = perAgent.filter((r) => !r.ok);
     if (failed.length === 0) {
-      return { envelope: ok({ agents: perAgent }), exitKind: 'ok' };
+      return { envelope: ok({ agents: perAgent }, refreshHint(perAgent, wasInstalled)), exitKind: 'ok' };
     }
     return {
       envelope: fail(
@@ -1171,6 +1196,7 @@ function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
       exitKind: 'invalid_input',
     };
   }
+  const wasInstalled = installedBefore(inspect, projectRoot);
   const r = applyOneAdapter(adapter, agent, projectRoot);
   if (!r.ok) {
     // A malformed host config is the user's input, not an environment fault —
@@ -1188,11 +1214,21 @@ function handleInit({ projectRoot, adapters = ADAPTERS }, agent) {
     };
   }
   return {
-    envelope: ok({ agent: r.agent, written: r.written, merged: r.merged }),
+    envelope: ok({ agent: r.agent, changes: r.changes }, refreshHint([r], wasInstalled)),
     exitKind: 'ok',
   };
 }
 
+// `mauto doctor` (#144): report whether the host integration `mauto init`
+// wrote is missing or out of date. A report, not a gate — always ok. The
+// report itself (data + hint) lives in src/init/doctor.js; this is the
+// handler-shape adapter to the emit contract. An unexpected fs error from the
+// inspection (EACCES, ...) is left to the envelope boundary to classify.
+function handleDoctor({ projectRoot, inspect = inspectHosts }) {
+  const { data, hint } = doctorReport({ projectRoot, inspect });
+  return { envelope: ok(data, hint), exitKind: 'ok' };
+}
+
 // --- Issue #91: persistent device session daemon -------------------------
 //
 // `mauto session start|status|end` manage the per-workspace daemon that holds
@@ -2125,6 +2161,13 @@ function buildProgram(deps = {}) {
       emit(r, humanFlag());
     }));
 
+  // No requireWorkspace: like guide, doctor runs on the discovered workspace
+  // or cwd, and must work before `mauto setup` has ever run.
+  program
+    .command('doctor')
+    .description("Report whether this project's agent integration (mauto init) is missing or out of date")
+    .action(withEnvelope(() => emit(handleDoctor({ projectRoot }), humanFlag())));
+
   // --- Issue #91: device session lifecycle ---------------------------------
 
   const session = program
@@ -2497,6 +2540,7 @@ module.exports = {
   handleMemoryAdd,
   handleMemoryForget,
   handleInit,
+  handleDoctor,
   handleSessionStart,
   handleSessionStatus,
   handleSessionEnd,

package/src/config/schema.js

@@ -12,14 +12,14 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv');
 
 const { formatError } = require('../schemas/format-error');
+const { createCliAjv } = require('../schemas/cli-ajv');
 
 const CONFIG_SCHEMA_PATH = path.resolve(__dirname, '../schemas/config_schema.json');
 
 const schema = JSON.parse(fs.readFileSync(CONFIG_SCHEMA_PATH, 'utf8'));
-const ajv = new Ajv({ allErrors: true, strict: false });
+const ajv = createCliAjv();
 
 // Resolve a local `$ref` ("#/definitions/stringList") to a fixpoint: a
 // resolved node may itself be another `$ref` (e.g. a `$ref` to a `$ref`), so

package/src/guide/emitter.js

@@ -113,6 +113,7 @@ function emitBootstrap() {
     ['result', 'record step results and finalize a run'],
     ['setup', 'scaffold the workspace and write a config'],
     ['config', 'get/set values in the workspace config'],
+    ['doctor', 'report whether the agent integration `mauto init` installed is missing or out of date'],
     ['guide', 'print the guide for a workflow topic'],
     ['schema', 'print the scenario, result, or config JSON schema'],
   ];

package/src/init/adapters.js

@@ -7,82 +7,30 @@
 // yields byte-identical files). claude/cursor additionally keep writing their
 // thin slash-command/rule and merging the shared `mauto` MCP server entry.
 // Adapters never clobber a file they don't own.
+//
+// WHAT each host owns lives in host-plan.js (`planHost`); this module only
+// applies that plan, so the staleness detector and the writers share one
+// source (#144).
 
 const fs = require('fs');
 const path = require('path');
 
-const guideEmitter = require('../guide/emitter');
-const { renderSkill, readInvariants, SKILL_TOPICS } = require('./skill-renderer');
-const { SKILL_META } = require('./skill-meta');
-
-const TOPICS = ['generate', 'execute', 'setup'];
-
-// The single mauto MCP server entry merged into a vendor's mcp config.
-const MAUTO_SERVER = { command: 'mauto', args: ['mcp'] };
-
-// Per-agent skills directory (relative to projectRoot). claude uses its own
-// namespace; cursor/gemini/copilot each use their native dir; `agents` targets
-// the open-standard location.
-const SKILL_DEST = {
-  claude: path.join('.claude', 'skills'),
-  cursor: path.join('.cursor', 'skills'),
-  gemini: path.join('.gemini', 'skills'),
-  copilot: path.join('.github', 'skills'),
-  agents: path.join('.agents', 'skills'),
-};
-
-// BACK-COMPAT FALLBACK — NOT the live instruction surface for a current host.
-//
-// Claude Code merged custom commands into skills, and a same-named skill wins:
-//   "if a skill and a command share the same name, the skill takes precedence"
-//   https://code.claude.com/docs/en/skills
-// We write both `mobile-automator-<topic>.md` here and a skill folder of the
-// same name, so on any host with skills support THIS FILE IS NEVER READ.
-// Editing it to change agent behavior on a current host does nothing — change
-// `<topic>.invariants.md` (directives) or the guide content (workflow) instead.
-//
-// It still wins in two places, which is why it is kept and why it must not be
-// thin: a Claude Code old enough to predate skills, and a workspace whose last
-// `mauto init` predates the release that started writing skills. On both, this
-// file IS the registered surface — so it renders from the same two sources the
-// skill does (`SKILL_META` + `<topic>.invariants.md`) and can never drift into
-// being the weaker of the two. The `description` frontmatter matters for the
-// same reason: without it a host derives one by truncating the body, which
-// yields a description of the mechanism rather than of when to use this.
-function claudeCommandBody(topic) {
-  return (
-    '---\n' +
-    `description: ${SKILL_META[topic].description}\n` +
-    '---\n\n' +
-    `Run \`mauto guide ${topic}\` and follow it.\n\n` +
-    '## Non-negotiable directives (always apply)\n' +
-    `${readInvariants(topic)}\n`
-  );
-}
-
-function cursorRuleBody() {
-  return (
-    '---\n' +
-    'description: Mobile Automator — drive mobile QA through the mauto CLI.\n' +
-    'alwaysApply: true\n' +
-    '---\n\n' +
-    guideEmitter.emitBootstrap() +
-    '\nRun `mauto guide <topic>` (generate|execute|setup) before a workflow. ' +
-    'Drive the device only through `mauto` verbs.\n'
-  );
-}
+const { planHost, HOSTS, MAUTO_SERVER, SKILL_DEST } = require('./host-plan');
 
+// Returns 'created' | 'updated' | 'unchanged'.
 function writeIfChanged(filePath, content) {
   const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
-  if (prev === content) return false;
+  if (prev === content) return 'unchanged';
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
-  return true;
+  return prev === null ? 'created' : 'updated';
 }
 
+// Returns { changed, status } where status is 'created' | 'updated' | 'unchanged'.
 function mergeMcpConfig(filePath) {
   let doc = {};
-  if (fs.existsSync(filePath)) {
+  const existed = fs.existsSync(filePath);
+  if (existed) {
     const existing = fs.readFileSync(filePath, 'utf8');
     try {
       doc = JSON.parse(existing);
@@ -101,62 +49,31 @@ function mergeMcpConfig(filePath) {
   }
   doc.mcpServers.mauto = { ...MAUTO_SERVER };
   const next = JSON.stringify(doc, null, 2) + '\n';
-  const prev = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : null;
-  if (prev === next) return { changed: false };
+  const prev = existed ? fs.readFileSync(filePath, 'utf8') : null;
+  if (prev === next) return { changed: false, status: 'unchanged' };
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, next);
-  return { changed: true };
-}
-
-// Install one SKILL.md folder per topic under the agent's skills dir. Only the
-// folders we own are written; foreign skill folders are never touched.
-function writeSkills(projectRoot, agent, written) {
-  const root = path.join(projectRoot, SKILL_DEST[agent]);
-  for (const topic of SKILL_TOPICS) {
-    const { dirName, content } = renderSkill(topic);
-    const file = path.join(root, dirName, 'SKILL.md');
-    writeIfChanged(file, content);
-    written.push(file);
-  }
+  return { changed: true, status: prev === null ? 'created' : 'updated' };
 }
 
-function makeAdapter(agent, extra) {
+function makeAdapter(agent) {
   return {
     apply({ projectRoot }) {
-      const written = [];
-      const merged = [];
-      if (extra) extra({ projectRoot, written, merged });
-      writeSkills(projectRoot, agent, written);
-      return { agent, written, merged };
+      const plan = planHost(agent);
+      const changes = [];
+      for (const { rel, content } of plan.files) {
+        const file = path.join(projectRoot, rel);
+        changes.push({ path: file, status: writeIfChanged(file, content) });
+      }
+      if (plan.mcp) {
+        const mcpPath = path.join(projectRoot, plan.mcp);
+        changes.push({ path: mcpPath, status: mergeMcpConfig(mcpPath).status });
+      }
+      return { agent, changes };
     },
   };
 }
 
-const ADAPTERS = {
-  claude: makeAdapter('claude', ({ projectRoot, written, merged }) => {
-    const commandsDir = path.join(projectRoot, '.claude', 'commands');
-    for (const topic of TOPICS) {
-      const file = path.join(commandsDir, `mobile-automator-${topic}.md`);
-      writeIfChanged(file, claudeCommandBody(topic));
-      written.push(file);
-    }
-    const mcpPath = path.join(projectRoot, '.mcp.json');
-    mergeMcpConfig(mcpPath);
-    merged.push(mcpPath);
-  }),
-
-  cursor: makeAdapter('cursor', ({ projectRoot, written, merged }) => {
-    const rulePath = path.join(projectRoot, '.cursor', 'rules', 'mobile-automator.mdc');
-    writeIfChanged(rulePath, cursorRuleBody());
-    written.push(rulePath);
-    const mcpPath = path.join(projectRoot, '.cursor', 'mcp.json');
-    mergeMcpConfig(mcpPath);
-    merged.push(mcpPath);
-  }),
-
-  gemini: makeAdapter('gemini'),
-  copilot: makeAdapter('copilot'),
-  agents: makeAdapter('agents'),
-};
+const ADAPTERS = Object.fromEntries(HOSTS.map((agent) => [agent, makeAdapter(agent)]));
 
 module.exports = { ADAPTERS, MAUTO_SERVER, SKILL_DEST };

package/src/init/doctor.js

@@ -0,0 +1,30 @@
+'use strict';
+
+// `mauto doctor` (#144): report whether the host integration `mauto init`
+// wrote is missing or out of date. A report, not a gate — the CLI always
+// renders it as an ok envelope. The inspection is honest: an unexpected fs
+// error from inspectHosts (EACCES, ...) propagates to the caller's envelope
+// boundary to classify, it is never swallowed.
+
+const { HOSTS } = require('./host-plan');
+const { initCommands } = require('./stale-notice');
+
+// Returns { data, hint } for the `mauto doctor` envelope.
+function doctorReport({ projectRoot, inspect }) {
+  const installed = inspect(projectRoot).filter((h) => h.installed);
+  const stale = installed.filter((h) => h.stale).map((h) => h.agent);
+  const data = {
+    initialised: installed.length > 0,
+    hosts: installed.map(({ agent, stale: s, files, mcp }) => ({ agent, stale: s, files, mcp })),
+    stale,
+  };
+  let hint = null;
+  if (stale.length) {
+    hint = initCommands(stale).map((c) => `run \`${c}\``).join('; ');
+  } else if (installed.length === 0) {
+    hint = `no host integration found — run \`mauto init --agent <host>\` (${HOSTS.join(' | ')} | all)`;
+  }
+  return { data, hint };
+}
+
+module.exports = { doctorReport };

package/src/init/host-plan.js

@@ -0,0 +1,197 @@
+'use strict';
+
+// HostPlan — the single source of "what `mauto init --agent <host>` owns".
+//
+// Every byte init writes is a pure function of the installed package: the
+// rendered skills, the claude command bodies, the cursor rule and the `mauto`
+// MCP server entry. None of it reads config.json. So "is this host's
+// integration stale?" is answered by "would init write different bytes?" — no
+// version stamp exists or is needed (#144).
+//
+// The writers (adapters.js) and the detector (inspectHosts) both read
+// `planHost`, so detection cannot drift from what init actually writes.
+
+const fs = require('fs');
+const path = require('path');
+const { isDeepStrictEqual } = require('util');
+
+const guideEmitter = require('../guide/emitter');
+const { renderSkill, readInvariants, SKILL_TOPICS } = require('./skill-renderer');
+const { SKILL_META } = require('./skill-meta');
+
+const TOPICS = ['generate', 'execute', 'setup'];
+
+// The single mauto MCP server entry merged into a vendor's mcp config.
+const MAUTO_SERVER = { command: 'mauto', args: ['mcp'] };
+
+// Per-agent skills directory (relative to projectRoot). claude uses its own
+// namespace; cursor/gemini/copilot each use their native dir; `agents` targets
+// the open-standard location.
+const SKILL_DEST = {
+  claude: path.join('.claude', 'skills'),
+  cursor: path.join('.cursor', 'skills'),
+  gemini: path.join('.gemini', 'skills'),
+  copilot: path.join('.github', 'skills'),
+  agents: path.join('.agents', 'skills'),
+};
+
+const HOSTS = Object.keys(SKILL_DEST);
+
+// Filesystem errno values that mean "the workspace's integration files can't
+// be read the way they normally sit" — a file or its parent is missing,
+// unreadable, or a directory sits where a file is expected. The advisory
+// surfaces that consume the inspection without failing (`guide`'s notice,
+// init's pre-run probe) treat these as "say nothing", never as a reason to
+// fail the verb. Any other errno (or a non-errno throw) escapes: a defect in
+// the inspection itself must be visible, not silently absorbed.
+const ADVISORY_FS_CODES = new Set(['ENOENT', 'EACCES', 'EPERM', 'EISDIR', 'ENOTDIR']);
+
+// BACK-COMPAT FALLBACK — NOT the live instruction surface for a current host.
+//
+// Claude Code merged custom commands into skills, and a same-named skill wins:
+//   "if a skill and a command share the same name, the skill takes precedence"
+//   https://code.claude.com/docs/en/skills
+// We write both `mobile-automator-<topic>.md` here and a skill folder of the
+// same name, so on any host with skills support THIS FILE IS NEVER READ.
+// Editing it to change agent behavior on a current host does nothing — change
+// `<topic>.invariants.md` (directives) or the guide content (workflow) instead.
+//
+// It still wins in two places, which is why it is kept and why it must not be
+// thin: a Claude Code old enough to predate skills, and a workspace whose last
+// `mauto init` predates the release that started writing skills. On both, this
+// file IS the registered surface — so it renders from the same two sources the
+// skill does (`SKILL_META` + `<topic>.invariants.md`) and can never drift into
+// being the weaker of the two. The `description` frontmatter matters for the
+// same reason: without it a host derives one by truncating the body, which
+// yields a description of the mechanism rather than of when to use this.
+function claudeCommandBody(topic) {
+  return (
+    '---\n' +
+    `description: ${SKILL_META[topic].description}\n` +
+    '---\n\n' +
+    `Run \`mauto guide ${topic}\` and follow it.\n\n` +
+    '## Non-negotiable directives (always apply)\n' +
+    `${readInvariants(topic)}\n`
+  );
+}
+
+function cursorRuleBody() {
+  return (
+    '---\n' +
+    'description: Mobile Automator — drive mobile QA through the mauto CLI.\n' +
+    'alwaysApply: true\n' +
+    '---\n\n' +
+    guideEmitter.emitBootstrap() +
+    '\nRun `mauto guide <topic>` (generate|execute|setup) before a workflow. ' +
+    'Drive the device only through `mauto` verbs.\n'
+  );
+}
+
+// One SKILL.md folder per topic under the agent's skills dir. Only the folders
+// we own are listed; foreign skill folders are never part of the plan.
+function skillFiles(agent) {
+  return SKILL_TOPICS.map((topic) => {
+    const { dirName, content } = renderSkill(topic);
+    return { rel: path.join(SKILL_DEST[agent], dirName, 'SKILL.md'), content };
+  });
+}
+
+// Everything init owns for one host, in write order. `files` are written whole;
+// `mcp` (when non-null) is the host config into which the `mauto` server entry
+// is merged. Paths are relative to the project root.
+function planHost(agent) {
+  if (!Object.prototype.hasOwnProperty.call(SKILL_DEST, agent)) {
+    throw new Error(`unknown agent: ${agent}`);
+  }
+  const files = [];
+  let mcp = null;
+  if (agent === 'claude') {
+    for (const topic of TOPICS) {
+      files.push({
+        rel: path.join('.claude', 'commands', `mobile-automator-${topic}.md`),
+        content: claudeCommandBody(topic),
+      });
+    }
+    mcp = '.mcp.json';
+  } else if (agent === 'cursor') {
+    files.push({
+      rel: path.join('.cursor', 'rules', 'mobile-automator.mdc'),
+      content: cursorRuleBody(),
+    });
+    mcp = path.join('.cursor', 'mcp.json');
+  }
+  files.push(...skillFiles(agent));
+  return { files, mcp };
+}
+
+function readOrNull(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+// The mauto entry is compared semantically — the user's formatting, key order
+// and other servers never make a host look stale.
+function inspectMcp(file) {
+  const raw = readOrNull(file);
+  if (raw === null) return { status: 'missing', hasEntry: false };
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    return { status: 'unreadable', hasEntry: false };
+  }
+  if (doc == null || typeof doc !== 'object' || Array.isArray(doc)) {
+    return { status: 'unreadable', hasEntry: false };
+  }
+  const servers = doc.mcpServers;
+  const entry =
+    servers && typeof servers === 'object' && !Array.isArray(servers) ? servers.mauto : undefined;
+  if (entry === undefined) return { status: 'missing', hasEntry: false };
+  return {
+    status: isDeepStrictEqual(entry, MAUTO_SERVER) ? 'current' : 'outdated',
+    hasEntry: true,
+  };
+}
+
+// Per-host report of what init owns vs. what is on disk. Never throws on a
+// malformed host config (that is reported as 'unreadable').
+function inspectHosts(projectRoot) {
+  return HOSTS.map((agent) => {
+    const plan = planHost(agent);
+    let installed = false;
+    const files = plan.files.map(({ rel, content }) => {
+      const abs = path.join(projectRoot, rel);
+      const onDisk = readOrNull(abs);
+      if (onDisk !== null) installed = true;
+      const status = onDisk === null ? 'missing' : onDisk === content ? 'current' : 'outdated';
+      return { path: abs, status };
+    });
+    let mcp = null;
+    if (plan.mcp) {
+      const abs = path.join(projectRoot, plan.mcp);
+      const { status, hasEntry } = inspectMcp(abs);
+      if (hasEntry) installed = true;
+      mcp = { path: abs, status };
+    }
+    const stale =
+      installed &&
+      (files.some((f) => f.status !== 'current') || (mcp !== null && mcp.status !== 'current'));
+    return { agent, installed, stale, files, mcp };
+  });
+}
+
+module.exports = {
+  HOSTS,
+  ADVISORY_FS_CODES,
+  MAUTO_SERVER,
+  SKILL_DEST,
+  TOPICS,
+  claudeCommandBody,
+  cursorRuleBody,
+  planHost,
+  inspectHosts,
+};

package/src/init/skill-renderer.js

@@ -21,7 +21,7 @@ const TITLES = {
 
 // The non-negotiable directives for a topic, verbatim from disk. Exported so
 // every surface that has to carry these directives renders them from this one
-// source rather than restating them — see `claudeCommandBody` in adapters.js.
+// source rather than restating them — see `claudeCommandBody` in host-plan.js.
 function readInvariants(topic) {
   return fs.readFileSync(path.join(CONTENT_DIR, `${topic}.invariants.md`), 'utf8').trim();
 }

package/src/init/stale-notice.js

@@ -0,0 +1,85 @@
+'use strict';
+
+// The advisory `mauto guide` prepends when a host integration that
+// `mauto init` wrote is missing or out of date (#144).
+//
+// Every surface init has ever written tells the agent to run
+// `mauto guide <topic>`, so a notice here reaches every stale workspace. It
+// tells the agent to TELL THE USER — init is never run on the user's behalf.
+//
+// The text is read by the agent alongside the guide, so it is held to the
+// guide lint guards: no OS names, no `{{`, no raw engine tool names
+// (tests/lint/stale-notice-fixture.js feeds it to them).
+
+const { HOSTS } = require('./host-plan');
+
+function byHostOrder(a, b) {
+  return HOSTS.indexOf(a) - HOSTS.indexOf(b);
+}
+
+// The init command(s) that refresh `agents`: one per host, in HOSTS order, or
+// the single `--agent all` when every host needs it.
+function initCommands(agents) {
+  const unique = [...new Set(agents)].sort(byHostOrder);
+  if (HOSTS.every((h) => unique.includes(h))) return ['mauto init --agent all'];
+  return unique.map((a) => `mauto init --agent ${a}`);
+}
+
+function describeHost(h) {
+  const statuses = h.files.map((f) => f.status);
+  if (h.mcp) statuses.push(h.mcp.status);
+  const missing = statuses.filter((s) => s === 'missing').length;
+  const outdated = statuses.filter((s) => s === 'outdated').length;
+  const parts = [];
+  if (missing) parts.push(`${missing} missing`);
+  if (outdated) parts.push(`${outdated} outdated`);
+  if (h.mcp && h.mcp.status === 'unreadable') parts.push('MCP config unreadable');
+  return `${h.agent} (${parts.join(', ')})`;
+}
+
+function joinList(items) {
+  if (items.length <= 2) return items.join(' and ');
+  return `${items.slice(0, -1).join(', ')}, and ${items[items.length - 1]}`;
+}
+
+// Which hosts already had an integration BEFORE this init run (#144). A
+// refresh of a host that was never installed is a fresh install, not an
+// upgrade, so it gets no hint. Advisory only — an inspection failure (an
+// unreadable workspace) must never fail init, so it means "no hosts".
+function installedBefore(inspect, projectRoot) {
+  try {
+    return new Set(inspect(projectRoot).filter((h) => h.installed).map((h) => h.agent));
+  } catch {
+    return new Set();
+  }
+}
+
+// `refreshed N stale file(s) for <agent>` for each previously-installed host
+// whose run created or updated anything; null when there is nothing to say.
+// `results` hold per-agent adapter results (`{ ok, agent, changes }`).
+function refreshHint(results, wasInstalled) {
+  const parts = [];
+  for (const r of results) {
+    if (!r.ok || !wasInstalled.has(r.agent)) continue;
+    const n = r.changes.filter((c) => c.status === 'created' || c.status === 'updated').length;
+    if (n > 0) parts.push(`refreshed ${n} stale file(s) for ${r.agent}`);
+  }
+  return parts.length ? parts.join('; ') : null;
+}
+
+// `staleHosts`: entries from inspectHosts() with `stale: true`. Returns a
+// markdown blockquote followed by a blank line, or '' when there is nothing
+// stale. Output is independent of input order.
+function renderStaleNotice(staleHosts) {
+  if (!staleHosts || staleHosts.length === 0) return '';
+  const hosts = [...staleHosts].sort((a, b) => byHostOrder(a.agent, b.agent));
+  const commands = initCommands(hosts.map((h) => h.agent)).map((c) => `\`${c}\``);
+  return (
+    '> **Notice — host integration out of date.** This project\'s agent integration was installed ' +
+    'by an older `mauto` and is missing or out of date: ' +
+    `${hosts.map(describeHost).join(', ')}. ` +
+    `Tell the user to run ${joinList(commands)} to refresh it, then continue with this guide.\n\n`
+  );
+}
+
+module.exports = { renderStaleNotice, initCommands, installedBefore, refreshHint };

package/src/observe/vocab.js

@@ -80,6 +80,7 @@ const VERB_NAMES = Object.freeze([
   'bootstrap',
   'memory',
   'init',
+  'doctor',
   'session',
   'devices',
   'crash',

package/src/scenario/validator.js

@@ -2,9 +2,9 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv');
 
 const { formatError } = require('../schemas/format-error');
+const { createCliAjv } = require('../schemas/cli-ajv');
 
 // Path to the canonical scenario schema, bundled inside the package.
 // src/scenario/validator.js -> ../schemas/scenario_schema.json
@@ -13,7 +13,7 @@ const DEFAULT_SCHEMA_PATH = path.resolve(__dirname, '../schemas/scenario_schema.
 class ScenarioValidator {
   constructor({ schemaPath = DEFAULT_SCHEMA_PATH } = {}) {
     const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
-    const ajv = new Ajv({ allErrors: true, strict: false });
+    const ajv = createCliAjv();
     this._validateFn = ajv.compile(schema);
   }
 

package/src/schemas/cli-ajv.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// The only place the CLI's Ajv instance is constructed (#191).
+//
+// There used to be two hand-copied `new Ajv({ allErrors: true, strict: false })`
+// literals — one in src/config/schema.js, one in src/scenario/validator.js —
+// plus a third mirror in the schema lint guard tied to them by nothing but a
+// comment. Three copies of "the CLI's own options" that nothing kept true:
+// change the options in src and the guard would keep vouching for the old
+// ones. A guard that hand-maintains a copy of the thing it guards is itself a
+// drift surface — the same lesson that produced docs-corpus.js.
+//
+// Everything that needs the CLI's Ajv — both call sites above, the unit tests
+// that validate envelopes against the shipped schemas, and
+// tests/lint/schemas-valid.test.js, which compiles every schema with the real
+// instance — now consumes this factory. That guard also fails on any other
+// construction site in src/ or bin/, so the options cannot quietly return as
+// literals.
+
+const Ajv = require('ajv');
+
+// allErrors: true — `mauto validate` and config validation report every
+// problem in one pass, not just the first one they hit.
+// strict: false — result_schema.json declares `format: "date-time"` and no
+// instance here registers formats, so strict mode would turn Ajv's warning
+// into an error. The CLI tolerates the warning rather than claim format
+// checking it does not actually do.
+function createCliAjv() {
+  return new Ajv({ allErrors: true, strict: false });
+}
+
+module.exports = { createCliAjv };