@fiodos/cli 0.1.18 → 0.1.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "description": "Fiodos CLI — analyzes your app's source code and generates the in-app voice-agent manifest, then wires the orb. Powers `npx @fiodos/cli analyze`.",
   "type": "commonjs",
   "bin": {

package/src/aiAnalyze.js

@@ -51,7 +51,7 @@ function resolveModel(model) {
 // focus the analysis — which folder/app, what to emphasize or ignore — but never
 // override the system rules, invent actions, skip verification or change the
 // output schema). When empty, the prompt is byte-identical to a spec-less run.
-const MAX_USER_SPEC_CHARS = 1000;
+const MAX_USER_SPEC_CHARS = 2500;
 
 function sanitizeUserSpec(raw) {
   if (raw == null) return '';
@@ -88,8 +88,10 @@ AppManifest (all fields required unless noted):
   "routes": [{
     "intent": string (snake_case, UNIQUE across routes AND actions),
     "label": string, "route": string (opaque route string for the app's navigation adapter — an expo-router href, a URL path, or "BACK"),
-    "description": string (one line: WHAT THIS SCREEN SHOWS and what the user can do there),
-    "examples": string[] (3-4 natural voice phrases, REQUIRED non-empty)
+    "description": string (one DISTINCTIVE line: what THIS screen shows and what the user does there, phrased so it can NOT be confused with sibling screens — name the concrete content/entities unique to it. e.g. "Lists the registered people/accounts; from here you open and manage each individual user" — NOT a generic "a screen of the app"),
+    "bubblePrompt": string (SHORT user-facing call-to-action shown in a small "thought bubble" next to the assistant orb WHEN THE USER IS ON THIS SCREEN. One friendly question/offer in the app's language, max ~6 words, ending naturally (often a "?"). Distinct per screen and tied to what the user does HERE — e.g. a cart screen: "¿Finalizar tu compra?"; a users list: "¿Buscar un usuario?"; a login screen: "¿Quieres iniciar sesión?". NOT a description, NOT the label verbatim. Optional — omit if nothing natural fits),
+    "actionIntents": string[] (OPTIONAL: intents of the actions a user performs FROM this screen — the action handlers actually wired into THIS screen's component/page. Use exact action intent ids from the "actions" array; [] if none. Advisory only, never gates anything),
+    "examples": string[] (5-8 natural voice phrases a user might say to reach this screen, REQUIRED non-empty. Include SYNONYMS and PARAPHRASES that do NOT contain the literal label word, so the agent recognizes indirect requests — e.g. for a "Users" screen: "ver usuarios", "la pantalla donde vemos a las personas", "muéstrame las cuentas", "lista de gente registrada", "quiénes están dados de alta". Vary the verb and the noun; cover the obvious phrasing AND at least two oblique ones. Avoid near-duplicates that differ only in a word)
   }],
   "actions": [{
     "intent": string (snake_case, UNIQUE across routes AND actions),
@@ -105,7 +107,7 @@ AppManifest (all fields required unless noted):
     "confirmationMessageTemplate": string (REQUIRED if requireConfirmation true),
     "parameters": { "<name>": {"type": "string"|"number"|"boolean", "required": boolean, "description": string (non-empty)} },
     "contextRequirements": {"requiresVisibleContent"?: bool, "requiresAuth"?: bool} (optional; set requiresAuth: true for actions that need a signed-in user — see the REQUIRES-AUTH rule below),
-    "examples": string[] (3-4 natural voice phrases, REQUIRED non-empty)
+    "examples": string[] (5-8 natural voice phrases a user might say to trigger this action, REQUIRED non-empty. Include SYNONYMS and PARAPHRASES that do NOT rely on the literal label word, so indirect requests are recognized — e.g. for "Empty cart": "vacía el carrito", "quita todo lo que tengo", "borra todos los productos de la cesta". Vary verb and phrasing; avoid near-duplicates)
   }],
   "policies": {"requireConfirmationForDestructive": true, "allowedWithoutAuth": string[], "contextRetentionTurns": 5}
 }
@@ -215,8 +217,18 @@ This is the context the agent reads to understand the app, so it can reason inst
 - effect: the observable outcome after it runs (state change, navigation, message).
 - relatedIntents: other manifest intents this naturally flows into or from (e.g. add-to-cart → checkout). Use the exact intent ids; [] if none.
 - route description: what the screen displays and what can be done there.
+- route actionIntents: for each screen, the intents of the actions whose handlers are actually wired into THAT screen's component/page (what the user can DO there). Use exact action intent ids; omit or [] when the screen is purely informational/navigational. This is "what you can do here" context — it never restricts the agent.
+- route bubblePrompt: a SHORT, friendly CTA (in the app's language, ~6 words max) the assistant shows beside the orb on THAT screen to invite the user to act — e.g. login screen → "¿Quieres iniciar sesión?", cart → "¿Finalizar tu compra?", users list → "¿Buscar un usuario?". Make it distinct per screen and grounded in what the user does there; it is end-user copy, not a description. Omit when nothing natural fits.
 - appType/appFlow: the app category and its main end-to-end flow.
-Be precise and concise — quality over volume. Never pad.
+
+DISTINCTIVENESS (this is what prevents the agent picking the wrong screen/action):
+- Two screens are EASILY confused when their descriptions are generic. Write each route's description so it names the concrete entities/content unique to THAT screen and could not be copy-pasted onto a sibling. Bad (confusable): "Dashboard screen of the app." Good: "Aggregate overview with KPI cards (totals of users, projects, revenue); it does NOT list individual records." vs "Lists individual user records with per-user detail."
+- EXAMPLES are how the agent maps indirect speech to the right intent. For every route AND action, after the obvious phrasing add at least TWO oblique phrasings that a real user would say WITHOUT the label word (descriptive references to the content, e.g. "where we see the people" for a Users screen, "the page with the totals/summary" for an Overview screen). This directly reduces cross-screen confusion. Make examples DISTINCT across sibling screens — never give two screens an example that would fit both.
+
+SENSITIVE ACTIONS — EXTRA DETAIL (still static, no per-turn change):
+For any action with requireConfirmation true (delete/remove, logout, place/cancel orders, spend money, irreversible changes), make description, preconditions and effect noticeably MORE detailed than for normal actions: spell out exactly what is affected, what is irreversible, and the precise post-state. This richer manual lives in the static prompt so the agent reasons carefully about the stakes; it does NOT change the confirmation flow (the engine still enforces it).
+
+Be precise and DISTINCTIVE. Descriptions stay one tight line each (no padding), but examples should be VARIED and cover several real phrasings (synonyms/paraphrases are wanted, near-duplicate filler is not).
 
 Also return EVIDENCE for every route and action: the file (exact relative path as given in the FILE headers) and symbol (function/property name) in the provided code that justifies it. Evidence is verified mechanically afterwards: an action whose file or symbol does not exist is dropped, and unverifiable items count against you.
 
@@ -352,12 +364,75 @@ function buildUserPrompt(appMeta, files, omitted, staticRoutes, surface = null,
   );
 }
 
+/**
+ * Extract the FIRST complete, balanced JSON object from `text`, scanning from
+ * the first `{` to its matching `}` while respecting string literals and escape
+ * sequences (so braces inside string values don't throw the counter off).
+ * Returns the substring, or null when no balanced object is found.
+ *
+ * This is what makes parsing robust to a model that emits trailing prose (or a
+ * second brace-bearing sentence) after an otherwise valid JSON object — the
+ * cause of "Unexpected non-whitespace character after JSON at position N".
+ */
+function extractBalancedJsonObject(text) {
+  const start = text.indexOf('{');
+  if (start < 0) return null;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < text.length; i += 1) {
+    const ch = text[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === '\\') {
+      if (inString) escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === '{') {
+      depth += 1;
+    } else if (ch === '}') {
+      depth -= 1;
+      if (depth === 0) return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
 function parseJsonContent(raw) {
   let trimmed = (raw || '').trim();
   if (!trimmed) return {};
+  // Strip a leading/trailing markdown code fence if the model wrapped its JSON.
   if (trimmed.startsWith('```')) {
     trimmed = trimmed.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/i, '').trim();
   }
+  // 1) Happy path: the response is exactly one JSON value.
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    /* fall through to tolerant extraction */
+  }
+  // 2) Tolerant path: take the FIRST balanced {…} object and ignore anything
+  //    the model appended after it (trailing prose, a second sentence, a stray
+  //    fence). A brace-aware scan beats indexOf('{')+lastIndexOf('}'), which
+  //    OVER-captures when the trailing text itself contains braces — the exact
+  //    failure mode ("Unexpected non-whitespace character after JSON").
+  const balanced = extractBalancedJsonObject(trimmed);
+  if (balanced) {
+    try {
+      return JSON.parse(balanced);
+    } catch {
+      /* fall through to the legacy widest-slice as a last resort */
+    }
+  }
+  // 3) Last resort: widest {…} slice (previous behavior) so we never regress on
+  //    inputs the old path could handle.
   const start = trimmed.indexOf('{');
   const end = trimmed.lastIndexOf('}');
   if (start < 0 || end <= start) throw new Error('Model response is not JSON');
@@ -578,4 +653,7 @@ module.exports = {
   sanitizeUserSpec,
   MAX_USER_SPEC_CHARS,
   manifestSchemaDoc,
+  // Exported so the response parser is unit-testable without a live AI call.
+  parseJsonContent,
+  extractBalancedJsonObject,
 };

package/src/changeRegistry.js

@@ -0,0 +1,534 @@
+/**
+ * changeRegistry — transparent, per-file record of every change the Fiodos
+ * installer makes in the client's repo.
+ *
+ * On each install / re-analysis run we write:
+ *   · `.fyodos/changes/<runId>.json` — structured snapshot of THIS run (machine-readable)
+ *   · `.fyodos/changes/index.json`     — chronological index of all runs
+ *   · `src/fyodos/FYODOS_CHANGES.md`   — human-readable log (APPENDS; history is never lost)
+ *
+ * SECURITY: never embed API keys, secrets, or env values — only file paths, variable
+ * names, and descriptions of what was touched.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const CLI_VERSION = require('../package.json').version;
+
+function normRel(appRoot, absOrRel) {
+  const rel = path.isAbsolute(absOrRel) ? path.relative(appRoot, absOrRel) : absOrRel;
+  return String(rel || '').replace(/\\/g, '/');
+}
+
+function resolveFyodosDirRel(appRoot) {
+  if (fs.existsSync(path.join(appRoot, 'src'))) return 'src/fyodos';
+  return 'fyodos';
+}
+
+function makeRunId() {
+  return new Date().toISOString().replace(/[:.]/g, '-');
+}
+
+function readJsonSafe(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function uniquePaths(list) {
+  const seen = new Set();
+  const out = [];
+  for (const item of list) {
+    const key = item.path;
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(item);
+  }
+  return out;
+}
+
+// ── Phase summarizers ────────────────────────────────────────────────────────
+
+function summarizeOrb(result) {
+  if (!result) return { status: 'skipped', applied: false };
+  const base = { status: result.status, mountFile: result.file || null };
+  switch (result.status) {
+    case 'added':
+      return {
+        ...base,
+        applied: true,
+        strategy: result.planSummary?.strategy || null,
+        steps: result.planSummary?.steps || [],
+        files: result.planSummary?.files || [],
+        created: result.planSummary?.created || [],
+        revert:
+          'Remove the blocks between `FYODOS:ORB:START` and `FYODOS:ORB:END` (and the Fiodos import). See `FYODOS_ORB_MOUNT.md`.',
+      };
+    case 'already':
+      return {
+        ...base,
+        applied: false,
+        note: 'The orb was already mounted from a previous run; no orb files were changed.',
+      };
+    case 'declined':
+      return {
+        ...base,
+        applied: false,
+        note: 'You declined the automatic orb mount; your source files were not modified.',
+      };
+    case 'declined-noninteractive':
+      return {
+        ...base,
+        applied: false,
+        note: 'Non-interactive terminal: orb mount was skipped. Re-run with --yes to apply.',
+      };
+    case 'printed':
+    case 'reverted':
+    case 'failed':
+      return {
+        ...base,
+        applied: false,
+        reason: result.reason || result.error || null,
+        note: 'Automatic orb mount did not complete; see the CLI output for the manual snippet.',
+      };
+    case 'skipped':
+      return { ...base, applied: false, note: 'Orb wiring was skipped (--no-wire / --no-orb-wire).' };
+    default:
+      return { ...base, applied: false };
+  }
+}
+
+function summarizeHandlers(result, appRoot) {
+  if (!result) return { status: 'skipped', applied: false };
+  const base = {
+    status: result.status,
+    autoCount: result.autoCount || 0,
+    manualCount: result.manualCount || 0,
+    docPath: result.docPath && appRoot ? normRel(appRoot, result.docPath) : null,
+  };
+  const applied = result.status === 'applied' || result.status === 'applied-untested';
+
+  if (applied) {
+    const bridgeEdits = (result.editedFiles || []).map((f) => ({
+      path: normRel('', f),
+      what:
+        'Added reversible `FYODOS:BRIDGE:START` / `FYODOS:BRIDGE:END` blocks (import + registerFiodosBridge call).',
+      intents: (result.plan?.auto || [])
+        .filter((e) => e.kind === 'bridge' && e.bridge?.file === f)
+        .map((e) => e.intent),
+      revert: 'Delete the `FYODOS:BRIDGE:START` … `FYODOS:BRIDGE:END` blocks in this file.',
+    }));
+    return {
+      ...base,
+      applied: true,
+      registryFile: result.registryFile ? normRel('', result.registryFile) : null,
+      bridgeFile: result.bridgeFile ? normRel('', result.bridgeFile) : null,
+      editedFiles: bridgeEdits,
+      wiredIntents: (result.plan?.auto || []).map((e) => e.intent),
+      manualIntents: (result.plan?.manual || result.plan?.review || []).map((e) => e.intent),
+      revert:
+        'Delete generated files under `src/fyodos/` (handlers.generated.*, bridge.*) and remove `FYODOS:BRIDGE` blocks from your components. See `FYODOS_HANDLERS.md`.',
+    };
+  }
+
+  const docAlways =
+    result.docPath &&
+    ['declined', 'declined-noninteractive', 'manual-only', 'applied', 'applied-untested', 'reverted'].includes(
+      result.status,
+    );
+
+  return {
+    ...base,
+    applied: false,
+    docWritten: Boolean(docAlways),
+    note:
+      result.status === 'declined'
+        ? 'You declined handler wiring; only the documentation file was written.'
+        : result.status === 'declined-noninteractive'
+          ? 'Non-interactive: handler wiring skipped. Documentation was written; re-run with --wire-yes to apply.'
+          : result.status === 'manual-only'
+            ? 'No actions could be wired automatically; see FYODOS_HANDLERS.md for manual steps.'
+            : result.status === 'no-actions'
+              ? 'Manifest has no actions; handler wiring was not needed.'
+              : result.status === 'skipped'
+                ? 'Handler wiring skipped (--no-wire).'
+                : result.status === 'reverted'
+                  ? 'Wiring was reverted because the post-install build failed.'
+                  : null,
+  };
+}
+
+function summarizeRegistries(result) {
+  if (!result) return { status: 'skipped', applied: false };
+  const base = { status: result.status, file: result.file || null };
+  switch (result.status) {
+    case 'connected':
+      return {
+        ...base,
+        applied: true,
+        what: 'Added `registries={fyodosGeneratedRegistries}` to `<FiodosAgent />` inside the existing `FYODOS:ORB` block.',
+        revert: 'Remove the `registries={…}` prop and its import from the orb mount file.',
+      };
+    case 'already':
+      return { ...base, applied: false, note: 'Registries were already connected.' };
+    case 'no-registry':
+    case 'no-target':
+    case 'not-mounted':
+    case 'unsupported-framework':
+      return { ...base, applied: false, note: 'Registry connection was not applicable for this framework/state.' };
+    default:
+      return { ...base, applied: false };
+  }
+}
+
+function summarizeEnv(result) {
+  if (!result) return { status: 'skipped', applied: false };
+  const wp = result.writePlan;
+  const base = { status: result.status };
+  if (result.status === 'written' && wp) {
+    return {
+      ...base,
+      applied: true,
+      envFile: wp.targetRel || wp.file || null,
+      variables: [wp.plan?.keyVar, wp.plan?.urlVar].filter(Boolean),
+      gitignoreUpdated: true,
+      note: 'API key and URL were written to your local env file (values are NOT recorded here). `.gitignore` was updated if needed.',
+      revert: `Remove the Fiodos lines from ${wp.targetRel || 'your env file'}.`,
+    };
+  }
+  if (result.status === 'already aligned') {
+    return { ...base, applied: false, note: 'Local env already matched the published project key.' };
+  }
+  if (result.status === 'declined by user') {
+    return { ...base, applied: false, note: 'You declined writing the API key to your local env file.' };
+  }
+  if (result.status === 'manual') {
+    return {
+      ...base,
+      applied: false,
+      note: wp?.kind === 'manual-angular' ? 'Angular env must be set manually in environment.ts.' : 'Env write requires manual setup for this framework.',
+    };
+  }
+  return { ...base, applied: false };
+}
+
+function collectFileEntries(appRoot, ctx) {
+  const { orbResult, handlerResult, registryResult, envResult } = ctx;
+  const created = [];
+  const modified = [];
+  const docs = [];
+
+  const fyodosDir = resolveFyodosDirRel(appRoot);
+
+  // Orb
+  if (orbResult?.status === 'added' && orbResult.planSummary) {
+    for (const f of orbResult.planSummary.created || []) {
+      created.push({
+        path: f,
+        phase: 'orb',
+        what: 'Created by the orb mount installer.',
+        revert: 'Delete this file if it was created solely for Fiodos (see FYODOS_ORB_MOUNT.md).',
+      });
+    }
+    for (const f of orbResult.planSummary.files || []) {
+      if ((orbResult.planSummary.created || []).includes(f)) continue;
+      modified.push({
+        path: f,
+        phase: 'orb',
+        what: 'Injected `<FiodosAgent />` (or bootstrap equivalent) between `FYODOS:ORB:START` / `FYODOS:ORB:END` markers.',
+        revert: 'Remove the `FYODOS:ORB:START` … `FYODOS:ORB:END` block and the Fiodos import.',
+      });
+    }
+    docs.push({
+      path: `${fyodosDir}/FYODOS_ORB_MOUNT.md`,
+      phase: 'orb',
+      what: 'Human-readable orb mount summary (strategy, files, auth props).',
+    });
+  }
+
+  // Handlers — doc is written even when wiring is declined
+  if (handlerResult?.docPath) {
+    docs.push({
+      path: normRel(appRoot, handlerResult.docPath),
+      phase: 'handlers',
+      what: 'Action wiring plan: auto-wired actions, manual steps, security notes.',
+    });
+  }
+  if (
+    handlerResult &&
+    (handlerResult.status === 'applied' || handlerResult.status === 'applied-untested')
+  ) {
+    if (handlerResult.registryFile) {
+      created.push({
+        path: normRel(appRoot, handlerResult.registryFile),
+        phase: 'handlers',
+        what: 'Generated handler registry (`handlers.generated.*`). Regenerated on each apply.',
+        revert: 'Safe to delete; re-run the installer to regenerate.',
+      });
+    }
+    if (handlerResult.bridgeFile) {
+      created.push({
+        path: normRel(appRoot, handlerResult.bridgeFile),
+        phase: 'handlers',
+        what: 'Bridge module for component-registered live functions.',
+        revert: 'Safe to delete together with handlers.generated.*.',
+      });
+    }
+    for (const edit of summarizeHandlers(handlerResult).editedFiles || []) {
+      modified.push({ path: edit.path, phase: 'handlers', what: edit.what, revert: edit.revert, intents: edit.intents });
+    }
+  }
+
+  // Registry connection
+  if (registryResult?.status === 'connected' && registryResult.file) {
+    modified.push({
+      path: registryResult.file,
+      phase: 'registries',
+      what: 'Connected `registries={fyodosGeneratedRegistries}` to the mounted orb.',
+      revert: 'Remove the registries prop and its import from the orb mount.',
+    });
+  }
+
+  // Env (never record values)
+  if (envResult?.status === 'written' && envResult.writePlan?.targetRel) {
+    modified.push({
+      path: envResult.writePlan.targetRel,
+      phase: 'env',
+      what: `Upserted ${envResult.writePlan.plan?.keyVar || 'FYODOS_API_KEY'} (and URL var if applicable). Values not logged here.`,
+      revert: 'Remove the Fiodos env lines from this file.',
+    });
+    modified.push({
+      path: '.gitignore',
+      phase: 'env',
+      what: 'Ensured the env file is git-ignored so secrets are not pushed.',
+      revert: 'Optional: remove the Fiodos gitignore comment if you revert everything.',
+    });
+  }
+
+  // This registry itself
+  docs.push({
+    path: `${fyodosDir}/FYODOS_CHANGES.md`,
+    phase: 'registry',
+    what: 'This cumulative change log (appended each run).',
+  });
+  docs.push({
+    path: '.fyodos/changes/',
+    phase: 'registry',
+    what: 'Per-run JSON snapshots and index (machine-readable history).',
+  });
+
+  return {
+    created: uniquePaths(created),
+    modified: uniquePaths(modified),
+    docs: uniquePaths(docs),
+  };
+}
+
+function computeDelta(appRoot, current) {
+  const indexPath = path.join(appRoot, '.fyodos', 'changes', 'index.json');
+  const index = readJsonSafe(indexPath);
+  if (!index?.runs?.length) return null;
+
+  const prevPath = path.join(appRoot, '.fyodos', 'changes', index.runs[0].jsonFile);
+  const prev = readJsonSafe(prevPath);
+  if (!prev) return null;
+
+  const prevIntents = new Set(prev.phases?.handlers?.wiredIntents || []);
+  const currIntents = new Set(current.phases?.handlers?.wiredIntents || []);
+  const addedIntents = [...currIntents].filter((i) => !prevIntents.has(i));
+  const removedIntents = [...prevIntents].filter((i) => !currIntents.has(i));
+
+  const prevFiles = new Set([
+    ...(prev.files?.created || []).map((f) => f.path),
+    ...(prev.files?.modified || []).map((f) => f.path),
+  ]);
+  const currFiles = new Set([
+    ...(current.files?.created || []).map((f) => f.path),
+    ...(current.files?.modified || []).map((f) => f.path),
+  ]);
+  const newFiles = [...currFiles].filter((f) => !prevFiles.has(f));
+
+  return {
+    previousRunId: prev.runId,
+    previousTimestamp: prev.timestamp,
+    actionsAdded: addedIntents,
+    actionsRemoved: removedIntents,
+    newOrModifiedFiles: newFiles,
+    orbFirstInstall: prev.phases?.orb?.applied !== true && current.phases?.orb?.applied === true,
+  };
+}
+
+/**
+ * Build a structured record for one installer run from the phase results.
+ */
+function buildRunRecord(appRoot, ctx) {
+  const record = {
+    runId: makeRunId(),
+    timestamp: new Date().toISOString(),
+    cliVersion: CLI_VERSION,
+    appName: ctx.appName || path.basename(appRoot),
+    manifest: {
+      actionCount: (ctx.manifest?.actions || []).length,
+      routeCount: (ctx.manifest?.routes || []).length,
+      generatedAt: ctx.publishMeta?.generatedAt || null,
+    },
+    phases: {
+      orb: summarizeOrb(ctx.orbResult),
+      handlers: summarizeHandlers(ctx.handlerResult, appRoot),
+      registries: summarizeRegistries(ctx.registryResult),
+      env: summarizeEnv(ctx.envResult),
+    },
+    files: collectFileEntries(appRoot, ctx),
+  };
+  record.delta = computeDelta(appRoot, record);
+  return record;
+}
+
+function renderHeader() {
+  return [
+    '# Fiodos — change log',
+    '',
+    'Every time the Fiodos installer runs (initial install or re-analysis), an entry is **appended** below.',
+    'This is your transparency record: what Fiodos created or modified in your repo, file by file.',
+    '',
+    '- **Revert orb changes:** remove `FYODOS:ORB:START` … `FYODOS:ORB:END` blocks (see `FYODOS_ORB_MOUNT.md`).',
+    '- **Revert handler wiring:** delete `handlers.generated.*`, `bridge.*`, and `FYODOS:BRIDGE` blocks (see `FYODOS_HANDLERS.md`).',
+    '- **Machine-readable history:** `.fyodos/changes/` (one JSON file per run).',
+    '',
+    'No API keys or secrets appear in this log.',
+    '',
+    '---',
+  ].join('\n');
+}
+
+function renderFileList(title, items) {
+  if (!items?.length) return [];
+  const L = [`### ${title}`, ''];
+  for (const f of items) {
+    L.push(`- \`${f.path}\`${f.intents?.length ? ` — actions: ${f.intents.map((i) => `\`${i}\``).join(', ')}` : ''}`);
+    if (f.what) L.push(`  - ${f.what}`);
+    if (f.revert) L.push(`  - Revert: ${f.revert}`);
+  }
+  L.push('');
+  return L;
+}
+
+function renderRunSection(record) {
+  const L = [];
+  L.push(`## Run ${record.timestamp}`);
+  L.push('');
+  L.push(`- CLI: \`@fiodos/cli@${record.cliVersion}\``);
+  L.push(`- App: \`${record.appName}\``);
+  L.push(`- Manifest: ${record.manifest.actionCount} action(s), ${record.manifest.routeCount} route(s)`);
+  L.push(`- Run id: \`${record.runId}\``);
+  L.push('');
+
+  if (record.delta) {
+    L.push('### Changes vs previous run');
+    L.push('');
+    if (record.delta.actionsAdded.length) {
+      L.push(`- Actions newly wired: ${record.delta.actionsAdded.map((i) => `\`${i}\``).join(', ')}`);
+    }
+    if (record.delta.actionsRemoved.length) {
+      L.push(`- Actions no longer wired: ${record.delta.actionsRemoved.map((i) => `\`${i}\``).join(', ')}`);
+    }
+    if (record.delta.newOrModifiedFiles.length) {
+      L.push(`- Files touched this run: ${record.delta.newOrModifiedFiles.map((f) => `\`${f}\``).join(', ')}`);
+    }
+    if (!record.delta.actionsAdded.length && !record.delta.actionsRemoved.length && !record.delta.newOrModifiedFiles.length) {
+      L.push('- No file changes compared to the previous run (re-analysis only updated the manifest/backend).');
+    }
+    L.push('');
+  }
+
+  const phases = [
+    ['Orb mount', record.phases.orb],
+    ['Action handlers', record.phases.handlers],
+    ['Registry connection', record.phases.registries],
+    ['Environment', record.phases.env],
+  ];
+  for (const [label, ph] of phases) {
+    if (!ph || ph.status === 'skipped') continue;
+    L.push(`### ${label}`);
+    L.push('');
+    L.push(`- Status: \`${ph.status}\`${ph.applied ? ' (applied)' : ''}`);
+    if (ph.strategy) L.push(`- Strategy: \`${ph.strategy}\``);
+    if (ph.steps?.length) {
+      L.push('- Steps:');
+      for (const s of ph.steps) L.push(`  - ${s}`);
+    }
+    if (ph.note) L.push(`- ${ph.note}`);
+    if (ph.revert) L.push(`- Revert: ${ph.revert}`);
+    L.push('');
+  }
+
+  L.push(...renderFileList('Files created', record.files.created));
+  L.push(...renderFileList('Files modified', record.files.modified));
+  L.push(...renderFileList('Documentation generated', record.files.docs));
+
+  L.push('---');
+  return L.join('\n');
+}
+
+function briefSummary(record) {
+  const parts = [];
+  if (record.phases.orb.applied) parts.push('orb mounted');
+  if (record.phases.handlers.applied) parts.push(`${record.phases.handlers.autoCount} handlers wired`);
+  if (record.phases.registries.applied) parts.push('registries connected');
+  if (record.phases.env.applied) parts.push('env written');
+  const touched = record.files.created.length + record.files.modified.length;
+  if (!parts.length) parts.push('docs/analysis only');
+  return `${parts.join(', ')} · ${touched} file(s) touched`;
+}
+
+/**
+ * Persist the run record: JSON snapshot + append to FYODOS_CHANGES.md + update index.
+ */
+function writeChangeRegistry(appRoot, runRecord) {
+  const changesDir = path.join(appRoot, '.fyodos', 'changes');
+  fs.mkdirSync(changesDir, { recursive: true });
+
+  const jsonAbs = path.join(changesDir, `${runRecord.runId}.json`);
+  fs.writeFileSync(jsonAbs, `${JSON.stringify(runRecord, null, 2)}\n`);
+
+  const fyodosDir = resolveFyodosDirRel(appRoot);
+  const mdAbs = path.join(appRoot, fyodosDir, 'FYODOS_CHANGES.md');
+  fs.mkdirSync(path.dirname(mdAbs), { recursive: true });
+
+  const section = renderRunSection(runRecord);
+  if (fs.existsSync(mdAbs)) {
+    const existing = fs.readFileSync(mdAbs, 'utf8').trimEnd();
+    fs.writeFileSync(mdAbs, `${existing}\n\n${section}\n`);
+  } else {
+    fs.writeFileSync(mdAbs, `${renderHeader()}\n\n${section}\n`);
+  }
+
+  const indexAbs = path.join(changesDir, 'index.json');
+  const index = readJsonSafe(indexAbs) || { runs: [] };
+  index.runs.unshift({
+    runId: runRecord.runId,
+    timestamp: runRecord.timestamp,
+    cliVersion: runRecord.cliVersion,
+    jsonFile: `${runRecord.runId}.json`,
+    summary: briefSummary(runRecord),
+  });
+  fs.writeFileSync(indexAbs, `${JSON.stringify(index, null, 2)}\n`);
+
+  return {
+    mdRel: normRel(appRoot, mdAbs),
+    jsonRel: normRel(appRoot, jsonAbs),
+    indexRel: normRel(appRoot, indexAbs),
+  };
+}
+
+module.exports = {
+  buildRunRecord,
+  writeChangeRegistry,
+  resolveFyodosDirRel,
+  renderRunSection,
+  briefSummary,
+};

package/src/index.js

@@ -97,6 +97,7 @@ const { wireWebOrb, reportWireResult, connectOrbRegistries, reportRegistriesResu
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
 const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
 const { scoreSurface, computeSurface } = require('./scoreSurface');
+const { buildRunRecord, writeChangeRegistry } = require('./changeRegistry');
 
 function arg(flag, fallback) {
   const i = process.argv.indexOf(flag);
@@ -503,6 +504,9 @@ async function main() {
     const assumeYes = process.argv.includes('--yes') || process.argv.includes('--wire-yes');
     const noWire = process.argv.includes('--no-wire');
     let envWriteResult = null;
+    let orbWireResult = null;
+    let handlerWireResult = null;
+    let registryWireResult = null;
     const { runPostWireTest } = require('./postWireTest');
     const selfCorrect = !process.argv.includes('--no-self-correct');
     const corrector = selfCorrect
@@ -549,6 +553,7 @@ async function main() {
           noWire,
           runTest: !process.argv.includes('--no-wire-test'),
         });
+        orbWireResult = result;
         if (!assumeYes) resume();
         report(() => reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() }));
         orbMounted = result.status === 'added' || result.status === 'already';
@@ -576,6 +581,7 @@ async function main() {
       setLabel(wiringSpinnerLabel(platform));
       if (!assumeYes) pause();
       const handlerResult = await wireHandlers(analysisRoot, handlerOpts);
+      handlerWireResult = handlerResult;
       if (!assumeYes) resume();
       report(() => reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() }));
 
@@ -593,6 +599,7 @@ async function main() {
         const connected = connectOrbRegistries(analysisRoot, {
           registryFileAbs: handlerResult.registryFile,
         });
+        registryWireResult = connected;
         report(() => reportRegistriesResult(connected, fyodosTermColors(), { quiet: !isVerbose() }));
       }
 
@@ -650,6 +657,27 @@ async function main() {
         logDev(`[write-env] skipped: ${e.message}`);
       }
     }
+
+    // ── Change registry (transparency): record every file Fiodos touched ───────
+    // Appends to FYODOS_CHANGES.md and writes .fyodos/changes/<runId>.json.
+    // Runs after orb + handler + env so the record reflects the full pass.
+    if (!noWire) {
+      try {
+        const record = buildRunRecord(analysisRoot, {
+          appName: manifest.appName,
+          manifest,
+          publishMeta,
+          orbResult: orbWireResult,
+          handlerResult: handlerWireResult,
+          registryResult: registryWireResult,
+          envResult: envWriteResult,
+        });
+        const paths = writeChangeRegistry(analysisRoot, record);
+        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+      } catch (e) {
+        logDev(`[change-registry] could not write: ${e.message}`);
+      }
+    }
   } else if (publishing) {
     loadAppEnv(analysisRoot);
     await withSpinner('Publishing to your project', () =>
@@ -711,9 +739,32 @@ function detectPlatform(appRoot, appDir) {
   ) {
     return 'web';
   }
+  // The Fiodos SDK the developer installed states their target platform — the
+  // strongest intent signal in a mixed monorepo whose root has no framework dep
+  // of its own (e.g. EVO: root has @fiodos/react-native, the real Expo app lives
+  // in mobile/mobile/). Without this we'd wrongly default a mobile repo to 'web'
+  // and run the web orb wiring against a sibling Next.js app.
+  const sdkPlatform = fiodosSdkPlatform(deps);
+  if (sdkPlatform) return sdkPlatform;
   return appDir ? 'mobile' : 'web';
 }
 
+/**
+ * Platform implied by the installed Fiodos SDK. Returns 'mobile' | 'web' | null
+ * (null when both or neither are present — no unambiguous signal).
+ */
+function fiodosSdkPlatform(deps) {
+  if (!deps) return null;
+  const mobile = Boolean(deps['@fiodos/react-native']);
+  const web = Boolean(
+    deps['@fiodos/react'] || deps['@fiodos/vue'] || deps['@fiodos/svelte'] ||
+    deps['@fiodos/angular'] || deps['@fiodos/web-core'],
+  );
+  if (mobile && !web) return 'mobile';
+  if (web && !mobile) return 'web';
+  return null;
+}
+
 function readAppMeta(appRoot) {
   const meta = { name: path.basename(appRoot), description: '', dependencies: [] };
   const pkgPath = path.join(appRoot, 'package.json');

package/src/postWireTest.js

@@ -103,6 +103,30 @@ function tail(s, n = 60) {
   return lines.slice(-n).join('\n').trim();
 }
 
+/** Compact build failure for the terminal — not the full next/vite log. */
+function summarizeBuildOutput(raw, maxLines = 4) {
+  const lines = String(raw || '').split('\n');
+  const picked = [];
+  const push = (line) => {
+    const t = line.trim();
+    if (!t || picked.includes(t)) return;
+    if (/telemetry|Learn more:/i.test(t)) return;
+    if (/^▲ Next\.js/i.test(t)) return;
+    picked.push(t);
+  };
+  for (const line of lines) {
+    if (
+      /Module not found|Can't resolve|Failed to compile|error TS\d+|SyntaxError|ENOENT/i.test(line)
+    ) {
+      push(line);
+    }
+  }
+  if (picked.length === 0) {
+    for (const line of lines.slice(-maxLines)) push(line);
+  }
+  return picked.slice(0, maxLines).join('\n').trim();
+}
+
 async function runPostWireTest(appRoot, opts = {}) {
   const timeoutMs = opts.timeoutMs || 240000;
   if (!fs.existsSync(path.join(appRoot, 'node_modules'))) {
@@ -136,4 +160,4 @@ async function runPostWireTest(appRoot, opts = {}) {
   return { ok: res.status === 0, stage: chosen.stage, command: chosen.label, output };
 }
 
-module.exports = { runPostWireTest, chooseCommand };
+module.exports = { runPostWireTest, chooseCommand, summarizeBuildOutput, readPkg };

package/src/resolveAnalysisRoot.js

@@ -51,12 +51,49 @@ function platformDepsMatch(deps, platform) {
   return false;
 }
 
-function tryCandidate(appRoot, rel, platform, score) {
+/**
+ * How "complete" / runnable a candidate app folder looks. A monorepo can nest a
+ * thin source wrapper (e.g. mobile/) around the REAL runnable app (mobile/mobile/
+ * with app.json, the expo dep, native ios/android dirs). Conventional-name
+ * matching alone would pick the wrapper; this score lets the real app win.
+ */
+function appCompleteness(dir, platform) {
+  let score = 0;
+  const has = (rel) => fs.existsSync(path.join(dir, rel));
+  if (has('app') || has('src') || has('pages')) score += 2;
+  let pkg = {};
+  try {
+    pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+  } catch {
+    /* ignore */
+  }
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const scripts = pkg.scripts || {};
+  if (pkg.main) score += 2;
+  if (platform === 'mobile') {
+    if (has('app.json') || has('app.config.js') || has('app.config.ts')) score += 4;
+    if (deps.expo) score += 4;
+    if (has('ios') || has('android')) score += 2;
+    if (scripts.start || scripts.ios || scripts.android) score += 1;
+  } else if (platform === 'web') {
+    if (
+      has('next.config.js') || has('next.config.ts') || has('next.config.mjs') ||
+      has('vite.config.js') || has('vite.config.ts') || has('index.html') ||
+      has('angular.json') || has('svelte.config.js')
+    ) {
+      score += 4;
+    }
+    if (scripts.build || scripts.dev) score += 1;
+  }
+  return score;
+}
+
+function tryCandidate(appRoot, rel, platform, nameScore) {
   const dir = path.join(appRoot, rel);
   if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return null;
   const deps = readDeps(path.join(dir, 'package.json'));
   if (!platformDepsMatch(deps, platform)) return null;
-  return { root: dir, rel, score, reason: rel };
+  return { root: dir, rel, nameScore, complete: appCompleteness(dir, platform), reason: rel };
 }
 
 /**
@@ -112,8 +149,15 @@ function resolveAnalysisRoot(appRoot, platform) {
     return { root: abs, scoped: false, reason: 'no sub-app detected' };
   }
 
-  // Prefer higher score, then shorter path (closer to root).
-  candidates.sort((a, b) => b.score - a.score || a.rel.length - b.rel.length);
+  // Prefer the most complete/runnable app first (so a real nested app beats a
+  // thin same-named wrapper), then the conventional-name confidence, then the
+  // shorter path (closer to root).
+  candidates.sort(
+    (a, b) =>
+      b.complete - a.complete ||
+      b.nameScore - a.nameScore ||
+      a.rel.length - b.rel.length,
+  );
   const best = candidates[0];
   return {
     root: best.root,

package/src/verify.js

@@ -31,6 +31,63 @@ function fileHasIdentifier(content, identifier) {
   return re.test(content);
 }
 
+/**
+ * Upper bound on examples kept per route/action. The enriched prompt asks the
+ * model for 5-8 varied phrasings; this cap protects the cacheable system prompt
+ * from a runaway list while leaving generous room for real synonyms.
+ */
+const MAX_EXAMPLES = 10;
+
+/**
+ * Sanitize a manifest item's `examples` array WITHOUT ever dropping the item:
+ * trims, removes empties, deduplicates case-insensitively (first spelling wins),
+ * and caps the count. Fail-open: when the model returned nothing usable, falls
+ * back to a single phrase derived from the label/intent so the core validator's
+ * "non-empty examples" rule still passes (today's contract, never weakened).
+ */
+function sanitizeExamples(raw, fallbackLabel) {
+  const list = Array.isArray(raw) ? raw : [];
+  const seen = new Set();
+  const cleaned = [];
+  for (const entry of list) {
+    if (typeof entry !== 'string') continue;
+    const phrase = entry.replace(/\s+/g, ' ').trim();
+    if (!phrase) continue;
+    const key = phrase.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    cleaned.push(phrase);
+    if (cleaned.length >= MAX_EXAMPLES) break;
+  }
+  if (cleaned.length === 0) {
+    const fallback = String(fallbackLabel || '').replace(/\s+/g, ' ').trim();
+    if (fallback) cleaned.push(fallback);
+  }
+  return cleaned;
+}
+
+/**
+ * Max length (chars) of a route's `bubblePrompt` (the short orb CTA). The prompt
+ * asks for ~6 words; this is a generous hard cap so a runaway sentence can never
+ * bloat the bubble UI or the served manifest.
+ */
+const MAX_BUBBLE_PROMPT = 80;
+
+/**
+ * Sanitize a route's `bubblePrompt` (fail-open, item never dropped): trims,
+ * collapses whitespace, strips wrapping quotes, and caps the length. Returns
+ * undefined when there is nothing usable (the SDK then derives a fallback from
+ * the label/examples), so a bad value never sticks.
+ */
+function sanitizeBubblePrompt(raw) {
+  if (typeof raw !== 'string') return undefined;
+  let s = raw.replace(/\s+/g, ' ').trim();
+  s = s.replace(/^["'«»“”]+|["'«»“”]+$/g, '').trim();
+  if (!s) return undefined;
+  if (s.length > MAX_BUBBLE_PROMPT) s = s.slice(0, MAX_BUBBLE_PROMPT).trim();
+  return s || undefined;
+}
+
 /** Normalize an expo-router href for comparison: strip (groups), trailing /index. */
 function normalizeHref(href) {
   return ('/' + String(href || '')
@@ -179,8 +236,51 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
     return true;
   });
 
+  // Layer 2 — "what you can do here": keep each route's actionIntents fail-open.
+  // Only intents that survived action verification stay (a dangling intent
+  // pointing at a dropped/hallucinated action is silently removed, deduped).
+  // Empty/invalid → the field is removed entirely (Layer 1 still works).
+  const keptActionIntents = new Set(dedupedActions.map((a) => a.intent));
+  for (const route of dedupedRoutes) {
+    if (!Array.isArray(route.actionIntents)) {
+      delete route.actionIntents;
+      continue;
+    }
+    const seenIntent = new Set();
+    const cleaned = route.actionIntents.filter(
+      (i) => typeof i === 'string' && keptActionIntents.has(i) && !seenIntent.has(i) && seenIntent.add(i),
+    );
+    if (cleaned.length > 0) route.actionIntents = cleaned;
+    else delete route.actionIntents;
+  }
+
+  // Examples hygiene (fail-open): trim, dedupe and cap the enriched phrasings on
+  // every surviving route and action. Never drops the item; falls back to the
+  // label so the core validator's non-empty-examples rule still holds.
+  for (const route of dedupedRoutes) {
+    if (route.route === 'BACK') continue;
+    route.examples = sanitizeExamples(route.examples, route.label || route.intent);
+    let bubble = sanitizeBubblePrompt(route.bubblePrompt);
+    if (!bubble) {
+      try {
+        const { deriveBubblePromptFromContext, resolveMessages } = require('@fiodos/core');
+        bubble = sanitizeBubblePrompt(
+          deriveBubblePromptFromContext(route, resolveMessages('en'), {
+            locale: 'en',
+            actions: dedupedActions,
+          }),
+        );
+      } catch {
+        /* core unavailable — leave bubble unset */
+      }
+    }
+    if (bubble) route.bubblePrompt = bubble;
+    else delete route.bubblePrompt;
+  }
+
   // Schema coercion the model sometimes needs (same as the old engine).
   for (const action of dedupedActions) {
+    action.examples = sanitizeExamples(action.examples, action.label || action.intent);
     for (const spec of Object.values(action.parameters || {})) {
       if (spec.type === 'integer' || spec.type === 'float') spec.type = 'number';
       else if (!['string', 'number', 'boolean'].includes(spec.type)) spec.type = 'string';
@@ -199,4 +299,4 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
   };
 }
 
-module.exports = { verifyManifest, normalizeHref };
+module.exports = { verifyManifest, normalizeHref, sanitizeExamples, MAX_EXAMPLES };

package/src/wireWeb.js

@@ -13,7 +13,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
-const { runPostWireTest } = require('./postWireTest');
+const { runPostWireTest, summarizeBuildOutput, readPkg } = require('./postWireTest');
 const {
   assessMount,
   describePlan,
@@ -32,6 +32,16 @@ const {
   WRAPPER_BASENAME,
 } = require('./wireWebMount');
 
+function planSummary(appRoot, plan, createdFiles) {
+  const rel = (f) => path.relative(appRoot, f).replace(/\\/g, '/');
+  return {
+    strategy: plan.strategy,
+    files: (plan.files || []).map(rel),
+    created: (createdFiles || []).map(rel),
+    steps: describePlan(plan),
+  };
+}
+
 function readJsonSafe(file) {
   try {
     return JSON.parse(fs.readFileSync(file, 'utf8'));
@@ -163,8 +173,49 @@ function askYesNo(question) {
   });
 }
 
+const WEB_SDK_BY_FRAMEWORK = {
+  vue: '@fiodos/vue',
+  svelte: '@fiodos/svelte',
+  sveltekit: '@fiodos/svelte',
+  angular: '@fiodos/angular',
+};
+
+function expectedWebSdk(framework) {
+  return WEB_SDK_BY_FRAMEWORK[framework] || '@fiodos/react';
+}
+
+/**
+ * Detects the one misconfiguration that silently breaks the build: the developer
+ * installed the MOBILE SDK (@fiodos/react-native) in a web app. The mount writes
+ * `import { FiodosAgent } from '@fiodos/react'` (or the framework SDK), so the
+ * bundler then dies on "Can't resolve". We catch it up front and print a short,
+ * actionable note instead of dumping the whole build log.
+ *
+ * If no Fiodos SDK is installed at all we stay silent and let the mount proceed
+ * (the dashboard install step / post-wire build covers that path), so this never
+ * blocks a clean integration that simply hasn't run npm install yet.
+ */
+function webSdkMissing(appRoot, framework) {
+  const pkg = readPkg(appRoot);
+  const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const expected = expectedWebSdk(framework);
+  if (deps[expected] || deps['@fiodos/web-core']) return null;
+  if (deps['@fiodos/react-native']) {
+    return (
+      `installed @fiodos/react-native, but this web app needs ${expected} — ` +
+      `run npm install ${expected} @fiodos/core`
+    );
+  }
+  return null;
+}
+
 function printSnippet(target, framework, colors, appRoot, reason) {
   const { blue, cyan, dim, reset } = colors;
+  if (reason && reason.includes('@fiodos/react-native')) {
+    console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}${reason}${reset}`);
+    console.error(`${dim}Then re-run analyze — the orb mount will be automatic.${reset}\n`);
+    return;
+  }
   const ts = !target || target.ext === '.tsx';
   console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}add the orb to your web app (copy this):${reset}`);
   if (reason) {
@@ -242,6 +293,12 @@ async function wireWebOrb(appRoot, opts = {}) {
     return { status: 'printed', reason: plan.reason };
   }
 
+  const sdkGap = webSdkMissing(appRoot, framework);
+  if (sdkGap) {
+    printSnippet(target, framework, colors, appRoot, sdkGap);
+    return { status: 'printed', reason: sdkGap };
+  }
+
   if (!assumeYes) {
     printMountPreview(plan, colors);
   }
@@ -295,7 +352,7 @@ async function wireWebOrb(appRoot, opts = {}) {
       const test = await build();
       if (test.ok || test.stage === 'skipped-no-deps') {
         writeConsentDoc(appRoot, plan);
-        return { status: 'added', file: plan.rel, test };
+        return { status: 'added', file: plan.rel, test, planSummary: planSummary(appRoot, plan, createdFiles) };
       }
       // Build failed with the orb mounted — was the app building WITHOUT it?
       revertAll();
@@ -303,17 +360,22 @@ async function wireWebOrb(appRoot, opts = {}) {
       if (baseline.ok) {
         // Built before, fails now → the mount is the regression. Keep it reverted.
         printSnippet(target, framework, colors, appRoot, `mount caused a build regression — reverted (${test.command})`);
-        return { status: 'reverted', file: plan.rel, test, reason: test.output };
+        return {
+          status: 'reverted',
+          file: plan.rel,
+          test,
+          reason: summarizeBuildOutput(test.output),
+        };
       }
       // It was already not building (or not verifiable) before us → keep the orb.
       applyMount(plan);
       verifyMounted(plan);
       writeConsentDoc(appRoot, plan);
-      return { status: 'added', file: plan.rel, test, preexistingFailure: true };
+      return { status: 'added', file: plan.rel, test, preexistingFailure: true, planSummary: planSummary(appRoot, plan, createdFiles) };
     }
 
     writeConsentDoc(appRoot, plan);
-    return { status: 'added', file: plan.rel };
+    return { status: 'added', file: plan.rel, planSummary: planSummary(appRoot, plan, createdFiles) };
   } catch (err) {
     revertAll();
     printSnippet(target, framework, colors, appRoot, err.message || String(err));
@@ -338,8 +400,11 @@ function reportWireResult(result, colors = {}, opts = {}) {
       console.error(`${tag} · ${dim || ''}automatic mount not possible${result.reason ? `: ${result.reason}` : ''}. Paste the snippet above.${reset || ''}`);
       break;
     case 'reverted':
-      console.error(`${tag} · ✗ mount reverted — app would not build. Paste the snippet above or fix manually.`);
-      if (result.reason) console.error(`${dim}${result.reason}${reset}`);
+      console.error(`${tag} · ✗ mount reverted — app would not build.`);
+      if (result.reason) {
+        console.error(`${dim}${result.reason}${reset}`);
+      }
+      console.error(`${tag} · ${dim || ''}Fix the issue above, then re-run analyze or paste the snippet.${reset || ''}`);
       break;
     case 'failed':
       console.error(`${tag} · ✗ could not safely edit ${result.file}. Paste the snippet above.`);