@fiodos/cli 0.1.19 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "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,9 +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),
+    "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[] (3-4 natural voice phrases, REQUIRED non-empty)
+    "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),
@@ -106,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}
 }
@@ -217,8 +218,17 @@ This is the context the agent reads to understand the app, so it can reason inst
 - 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.
 
@@ -354,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');
@@ -580,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/index.js

@@ -94,6 +94,8 @@ const { resolveAnalysisRoot } = require('./resolveAnalysisRoot');
 const { analyzeWithAI, correctActionWiring, DEFAULT_MODEL, resolveModel } = require('./aiAnalyze');
 const { verifyManifest } = require('./verify');
 const { wireWebOrb, reportWireResult, connectOrbRegistries, reportRegistriesResult } = require('./wireWeb');
+const { wireReactNativeOrb, reportReactNativeWire } = require('./wireReactNative');
+const { wireFlutterOrb, writeFlutterEnv, reportFlutterWire } = require('./wireFlutter');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
 const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
 const { scoreSurface, computeSurface } = require('./scoreSurface');
@@ -678,7 +680,173 @@ async function main() {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
     }
+  } else if (platform === 'mobile' && publishing) {
+    // ── Mobile (Expo / React Native): mirror the web pipeline, adapted ─────────
+    // Same single command that publishes also mounts the orb (via the SDK's
+    // one-line <FiodosExpoAgent/>), records the install proof so the dashboard
+    // connection screen completes, writes the EXPO_PUBLIC_* env, and prints the
+    // EAS production step — exactly like web, just for an app.
+    loadAppEnv(analysisRoot);
+    const { apiKey, apiUrl } = resolveApiTarget();
+    const noWire = process.argv.includes('--no-wire');
+    let orbWireResult = null;
+    let envWriteResult = null;
+
+    await withSpinner('Publishing to your project', async ({ setLabel, pause, resume }) => {
+      await publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true });
+      if (!noWire && !process.argv.includes('--no-orb-wire')) {
+        setLabel(orbMountSpinnerLabel(platform));
+        orbWireResult = wireReactNativeOrb(analysisRoot, {
+          manifest,
+          colors: fyodosTermColors(),
+          noWire,
+        });
+        pause();
+        reportReactNativeWire(orbWireResult, fyodosTermColors(), { quiet: !isVerbose() });
+        resume();
+        // Install proof: only when the orb is genuinely wired into the code. If
+        // we could only print a snippet, we DON'T post — the dashboard then
+        // waits for the runtime heartbeat (FiodosProvider's reportOrbSeen) so a
+        // green tick always reflects a real mount, never a guess.
+        if (
+          apiKey &&
+          (orbWireResult.status === 'added' || orbWireResult.status === 'already')
+        ) {
+          const proof = await postOrbWired({
+            apiKey,
+            apiUrl,
+            file: orbWireResult.file || '',
+            platform: 'mobile',
+            actionsStatus: 'done',
+          });
+          if (proof && proof.ok === false && proof.reason !== 'no-api-key') {
+            logDev(`[orb-wired] mobile install proof not recorded (${proof.status || proof.reason}); dashboard will rely on the runtime ping`);
+          }
+        }
+      }
+    });
+    logUser('Published to your project');
+
+    // API key in the app environment (EXPO_PUBLIC_*) — same consent flow as web.
+    if (!process.argv.includes('--no-write-env')) {
+      try {
+        envWriteResult = await offerWriteEnv({
+          appRoot: analysisRoot,
+          apiKey,
+          apiUrl,
+          defaultApiUrl: DEFAULT_API_URL,
+          assumeYes: process.argv.includes('--write-env-yes'),
+          log: logUser,
+          logDev,
+        });
+        if (envWriteResult) printEnvManualReminder(envWriteResult, { logUser, logDev });
+      } catch (e) {
+        logDev(`[write-env] skipped: ${e.message}`);
+      }
+    }
+
+    // Production (EAS) reminder for the build-time public key. A CLI cannot (and
+    // must not) authenticate into the user's Expo account, so we print the exact
+    // step instead — mirroring the web deploy-provider reminder.
+    if (apiKey) printExpoProductionReminder({ apiKey, appRoot: analysisRoot });
+
+    if (!noWire) {
+      try {
+        const record = buildRunRecord(analysisRoot, {
+          appName: manifest.appName,
+          manifest,
+          publishMeta,
+          orbResult: orbWireResult,
+          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 (platform === 'flutter' && publishing) {
+    // ── Flutter: mirror the web/RN pipeline, adapted to Dart ──────────────────
+    // The Flutter SDK's one-line FiodosAgent self-fetches the published manifest
+    // by API key, so we don't write a manifest file. We publish, wrap lib/main's
+    // home: with FiodosAgent, record the install proof, write the dart-define env
+    // file, and print the run + production commands.
+    loadAppEnv(analysisRoot);
+    const { apiKey, apiUrl } = resolveApiTarget();
+    const noWire = process.argv.includes('--no-wire');
+    let orbWireResult = null;
+    let envWriteResult = null;
+
+    await withSpinner('Publishing to your project', async ({ setLabel, pause, resume }) => {
+      await publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true });
+      if (!noWire && !process.argv.includes('--no-orb-wire')) {
+        setLabel(orbMountSpinnerLabel(platform));
+        orbWireResult = wireFlutterOrb(analysisRoot, { colors: fyodosTermColors(), noWire });
+        pause();
+        reportFlutterWire(orbWireResult, fyodosTermColors(), { quiet: !isVerbose() });
+        resume();
+        // Install proof only when the orb is genuinely wired into main.dart. If
+        // we could only print a snippet, we DON'T post — the dashboard then waits
+        // for the runtime heartbeat (FiodosAgent posts orb-seen on warmUp).
+        if (
+          apiKey &&
+          (orbWireResult.status === 'added' || orbWireResult.status === 'already')
+        ) {
+          const proof = await postOrbWired({
+            apiKey,
+            apiUrl,
+            file: orbWireResult.file || '',
+            platform: 'flutter',
+            actionsStatus: 'done',
+          });
+          if (proof && proof.ok === false && proof.reason !== 'no-api-key') {
+            logDev(`[orb-wired] flutter install proof not recorded (${proof.status || proof.reason}); dashboard will rely on the runtime ping`);
+          }
+        }
+      }
+    });
+    logUser('Published to your project');
+
+    // Dart-define env file (git-ignored) so `flutter run` has the key without
+    // hardcoding the secret in committed source.
+    if (apiKey && !process.argv.includes('--no-write-env')) {
+      try {
+        envWriteResult = writeFlutterEnv(analysisRoot, {
+          apiKey,
+          apiUrl,
+          defaultApiUrl: DEFAULT_API_URL,
+        });
+        if (envWriteResult && envWriteResult.written) {
+          logUser(`API key saved to ${envWriteResult.file} (git-ignored).`);
+          if (envWriteResult.gitignore && envWriteResult.gitignore.changed) {
+            logUser(`Added ${envWriteResult.gitignore.pattern} to .gitignore so your key is never pushed to GitHub.`);
+          }
+        }
+      } catch (e) {
+        logDev(`[write-env] flutter skipped: ${e.message}`);
+      }
+    }
+
+    if (apiKey) printFlutterRunReminder({ apiKey, envFile: envWriteResult && envWriteResult.file });
+
+    if (!noWire) {
+      try {
+        const record = buildRunRecord(analysisRoot, {
+          appName: manifest.appName,
+          manifest,
+          publishMeta,
+          orbResult: orbWireResult,
+          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) {
+    // Native (iOS / Android): the orb ships through the native SDK — there is no
+    // JS/Dart entrypoint to wire here, so we only publish the manifest.
     loadAppEnv(analysisRoot);
     await withSpinner('Publishing to your project', () =>
       publishManifest(manifest, publishMeta, analysisToken, { skipSuccessLog: true }),
@@ -687,6 +855,52 @@ async function main() {
   }
 }
 
+/**
+ * How to run a Flutter app with the orb key (dev) and ship it (production).
+ * Flutter has no auto-loaded .env: the compile-time key is passed via
+ * --dart-define. We never touch the user's build pipeline — we print the exact
+ * commands, mirroring the web deploy reminder and the RN EAS reminder.
+ */
+function printFlutterRunReminder({ apiKey, envFile }) {
+  const file = envFile || 'fyodos.env.json';
+  logUser('Run your app with the orb — pass the key as a compile-time define (2 steps)');
+  console.log('  Step 1 — Dev run (reads the git-ignored env file we just wrote):');
+  console.log(`            flutter run --dart-define-from-file=${file}`);
+  console.log('');
+  console.log('  Step 2 — Production build — pass the same define to your release build / CI:');
+  console.log(`            flutter build apk --dart-define-from-file=${file}`);
+  console.log(`            (or --dart-define=FYODOS_API_KEY=${apiKey})`);
+}
+
+/**
+ * Production (EAS) step for Expo: EXPO_PUBLIC_* vars are inlined by Metro from
+ * the build environment. Local `.env` covers `expo start`, but cloud EAS builds
+ * (which never receive a git-ignored .env) need the key set in EAS env so the
+ * orb is not invisible in TestFlight / Play builds. We never touch the user's
+ * Expo account — we print the exact command + dashboard path.
+ */
+function printExpoProductionReminder({ apiKey, appRoot }) {
+  const usesEas = (() => {
+    try {
+      return fs.existsSync(path.join(appRoot, 'eas.json'));
+    } catch {
+      return false;
+    }
+  })();
+  logUser('Make the orb appear in PRODUCTION builds — add the key to EAS (2 steps)');
+  console.log('  Step 1 — Copy your orb key (this exact value):');
+  console.log(`            ${apiKey}`);
+  console.log('');
+  console.log('  Step 2 — Set it in your EAS build environment:');
+  console.log(`            eas env:create --name EXPO_PUBLIC_FYODOS_API_KEY --value ${apiKey} --environment production`);
+  console.log('            (or expo.dev → your project → Environment variables, then rebuild)');
+  if (!usesEas) {
+    console.log('');
+    console.log('            No eas.json yet? `expo start` already reads your local .env;');
+    console.log('            add the EAS variable when you set up cloud builds.');
+  }
+}
+
 /**
  * Resolve the target platform from package.json dependencies — the only signal
  * that reliably tells a Next.js App Router web app (which has an app/ dir) apart
@@ -739,9 +953,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');
@@ -956,6 +1193,7 @@ async function postOrbWired({
   apiKey,
   apiUrl,
   file,
+  platform = 'web',
   actionsStatus = 'pending',
   actionsTotal = 0,
   actionsDone = 0,
@@ -967,7 +1205,7 @@ async function postOrbWired({
       headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
       body: JSON.stringify({
         file: file || '',
-        platform: 'web',
+        platform,
         actionsStatus,
         actionsTotal,
         actionsDone,

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 || '')
@@ -197,8 +254,33 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
     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';
@@ -217,4 +299,4 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
   };
 }
 
-module.exports = { verifyManifest, normalizeHref };
+module.exports = { verifyManifest, normalizeHref, sanitizeExamples, MAX_EXAMPLES };

package/src/wireFlutter.js

@@ -0,0 +1,170 @@
+/**
+ * wireFlutter — auto-mount the Fiodos orb in a Flutter app, mirroring the web
+ * and React Native orb auto-mounts (wireWeb.js / wireReactNative.js) adapted to
+ * Dart / Flutter.
+ *
+ * The Flutter SDK already exposes a true one-line drop-in, FiodosAgent, that
+ * self-fetches the published manifest by API key, fetches the dashboard orb
+ * theme, posts the orb-seen heartbeat, and renders the themed orb. So there is
+ * no manifest file to write (unlike RN): we only
+ *   1. add `import 'package:fiodos_flutter/fiodos_flutter.dart';`, and
+ *   2. wrap the app's `home:` widget with FiodosAgent (reading the key from a
+ *      compile-time --dart-define, never hardcoding the secret in source).
+ *
+ * Edits are idempotent and reversible (FYODOS:ORB markers). The orb must live
+ * INSIDE MaterialApp/CupertinoApp (it needs a Directionality/Material ancestor),
+ * which is exactly where `home:` is — so we wrap there, not at runApp(). When the
+ * `home:` value is not a simple widget expression we DON'T touch the file: we
+ * print a short snippet instead (like the web/RN paths), and the caller then
+ * skips the install proof so the dashboard waits for the runtime heartbeat.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { ensureEnvGitIgnored } = require('./writeEnv');
+
+const IMPORT_START = '// FYODOS:ORB:START (auto-generated — safe to remove)';
+const IMPORT_END = '// FYODOS:ORB:END';
+const SDK_IMPORT = "import 'package:fiodos_flutter/fiodos_flutter.dart';";
+
+const MAIN_CANDIDATES = ['lib/main.dart'];
+
+function findMainDart(appRoot) {
+  for (const rel of MAIN_CANDIDATES) {
+    const abs = path.join(appRoot, rel);
+    if (fs.existsSync(abs)) return { abs, rel };
+  }
+  return null;
+}
+
+function insertImportAfterLastImport(source, block) {
+  const lines = source.split('\n');
+  let lastImport = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^\s*import\s+['"]/.test(lines[i])) lastImport = i;
+  }
+  if (lastImport === -1) return `${block}\n${source}`;
+  lines.splice(lastImport + 1, 0, block);
+  return lines.join('\n');
+}
+
+/**
+ * Match the `home:` value when it is a single, simple widget constructor — the
+ * common case (e.g. `home: const TodoListScreen()`, `home: MyHomePage(title: 'x')`).
+ * We deliberately do NOT try to parse arbitrarily nested expressions: a complex
+ * home (Builder, ternaries, nested constructors with parens) falls back to the
+ * snippet, never to a risky edit. Group 1 = the whole widget expr (with const).
+ */
+const HOME_RE = /home:\s*((?:const\s+)?[A-Za-z_][\w.]*\([^()]*\))/;
+
+/** Build the wired main.dart, or null when home: is not a simple widget. */
+function buildWiredMain(source) {
+  if (!HOME_RE.test(source)) return null;
+  const wrapped = source.replace(HOME_RE, (full, widget) =>
+    'home: FiodosAgent(\n' +
+    "        apiKey: const String.fromEnvironment('FYODOS_API_KEY'),\n" +
+    "        baseUrl: const String.fromEnvironment('FYODOS_API_URL', defaultValue: kFiodosDefaultApiUrl),\n" +
+    `        child: ${widget},\n` +
+    '      )',
+  );
+  const importBlock = `${IMPORT_START}\n${SDK_IMPORT}\n${IMPORT_END}`;
+  return insertImportAfterLastImport(wrapped, importBlock);
+}
+
+/** Copy-paste snippet shown when we cannot safely auto-wrap. */
+function mountSnippet() {
+  return (
+    `${SDK_IMPORT}\n\n` +
+    `// Wrap your app's home widget (inside MaterialApp) with FiodosAgent:\n` +
+    `home: FiodosAgent(\n` +
+    `  apiKey: const String.fromEnvironment('FYODOS_API_KEY'),\n` +
+    `  child: const MyHomePage(),\n` +
+    `),`
+  );
+}
+
+function printSnippet(colors, rel, reason) {
+  const { blue, cyan, dim, reset } = colors;
+  console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}add the orb to ${rel || 'lib/main.dart'}${reason ? ` (${reason})` : ''}:${reset}`);
+  console.error(mountSnippet());
+  console.error(`${dim}Then re-run analyze — the mount becomes automatic once home: is a simple widget.${reset}\n`);
+}
+
+/**
+ * Auto-mount the orb into a Flutter app.
+ * @returns {{status:'added'|'already'|'printed'|'skipped', file?:string, reason?:string}}
+ */
+function wireFlutterOrb(appRoot, { colors = {}, noWire = false } = {}) {
+  const main = findMainDart(appRoot);
+  if (!main) {
+    printSnippet(colors, null, 'no lib/main.dart found');
+    return { status: 'printed', reason: 'no-main' };
+  }
+
+  let source;
+  try {
+    source = fs.readFileSync(main.abs, 'utf8');
+  } catch (e) {
+    return { status: 'skipped', reason: `read-failed: ${e.message}` };
+  }
+
+  if (source.includes('FiodosAgent(') || source.includes('FYODOS:ORB')) {
+    return { status: 'already', file: main.rel };
+  }
+
+  if (noWire) return { status: 'skipped', reason: 'no-wire' };
+
+  const wired = buildWiredMain(source);
+  if (!wired) {
+    printSnippet(colors, main.rel, 'home: is not a simple widget');
+    return { status: 'printed', file: main.rel, reason: 'unrecognized-home' };
+  }
+
+  try {
+    fs.writeFileSync(main.abs, wired);
+  } catch (e) {
+    return { status: 'skipped', reason: `write-failed: ${e.message}` };
+  }
+  return { status: 'added', file: main.rel };
+}
+
+/**
+ * Flutter env: there is no auto-loaded `.env`. The compile-time keys are passed
+ * with --dart-define; the convention for a checked-in run command is a
+ * dart-define-from-file JSON. We write a git-ignored `fyodos.env.json` holding
+ * the publishable key + URL so `flutter run --dart-define-from-file=fyodos.env.json`
+ * works locally, and the secret never lands in committed source.
+ * @returns {{file:string, written:boolean, gitignore:object}}
+ */
+function writeFlutterEnv(appRoot, { apiKey, apiUrl, defaultApiUrl }) {
+  if (!apiKey) return { file: null, written: false, gitignore: null };
+  const rel = 'fyodos.env.json';
+  const abs = path.join(appRoot, rel);
+  const payload = { FYODOS_API_KEY: apiKey };
+  if (apiUrl && apiUrl !== defaultApiUrl) payload.FYODOS_API_URL = apiUrl;
+  fs.writeFileSync(abs, `${JSON.stringify(payload, null, 2)}\n`);
+  const gitignore = ensureEnvGitIgnored(appRoot, rel);
+  return { file: rel, written: true, gitignore };
+}
+
+function reportFlutterWire(result, colors = {}, { quiet = false } = {}) {
+  const { blue, cyan, dim, reset } = colors;
+  if (!result) return;
+  if (result.status === 'added') {
+    console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · orb mounted in ${result.file}`);
+  } else if (result.status === 'already' && !quiet) {
+    console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}orb already mounted in ${result.file}${reset}`);
+  }
+}
+
+module.exports = {
+  wireFlutterOrb,
+  writeFlutterEnv,
+  reportFlutterWire,
+  // exported for tests
+  buildWiredMain,
+  findMainDart,
+  HOME_RE,
+};

package/src/wireReactNative.js

@@ -0,0 +1,217 @@
+/**
+ * wireReactNative — auto-mount the Fiodos orb in an Expo Router app, mirroring
+ * the web orb auto-mount (wireWeb.js) but adapted to React Native.
+ *
+ * Web drops a one-line <FiodosAgent/> into the app entry. The RN counterpart is
+ * the SDK's <FiodosExpoAgent/> (from '@fiodos/react-native/expo'), which wires
+ * the provider + floating layer + Expo adapters + published orb design behind a
+ * single component. So here we:
+ *   1. write the published manifest to `fyodos/manifest.json`, and
+ *   2. wrap the Expo Router root layout's returned tree with <FiodosExpoAgent>.
+ *
+ * Edits are idempotent and reversible (FYODOS:ORB markers). When the layout is
+ * not in the safe, recognized shape we DON'T touch it — we print a short snippet
+ * instead (exactly like the web path), and the caller then skips the install
+ * proof so the dashboard waits for the runtime heartbeat rather than lying.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ORB_START = '{/* FYODOS:ORB:START (auto-generated — safe to remove) */}';
+const ORB_END = '{/* FYODOS:ORB:END */}';
+const IMPORT_START = '// FYODOS:ORB:START (auto-generated — safe to remove)';
+const IMPORT_END = '// FYODOS:ORB:END';
+
+const LAYOUT_CANDIDATES = [
+  'app/_layout.tsx',
+  'app/_layout.jsx',
+  'src/app/_layout.tsx',
+  'src/app/_layout.jsx',
+];
+
+function findRootLayout(appRoot) {
+  for (const rel of LAYOUT_CANDIDATES) {
+    const abs = path.join(appRoot, rel);
+    if (fs.existsSync(abs)) return { abs, rel };
+  }
+  return null;
+}
+
+/** Write the published manifest the SDK mounts from. Returns the rel path. */
+function writeManifestFile(appRoot, manifest) {
+  const dir = path.join(appRoot, 'fyodos');
+  fs.mkdirSync(dir, { recursive: true });
+  const file = path.join(dir, 'manifest.json');
+  fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+  return path.relative(appRoot, file);
+}
+
+/** Import path (POSIX) from the layout file to fyodos/manifest.json. */
+function manifestImportSpecifier(layoutAbs, appRoot) {
+  const manifestAbs = path.join(appRoot, 'fyodos', 'manifest.json');
+  let rel = path.relative(path.dirname(layoutAbs), manifestAbs);
+  rel = rel.split(path.sep).join('/');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  return rel;
+}
+
+function insertImportsAfterLastImport(source, block) {
+  const lines = source.split('\n');
+  let lastImport = -1;
+  for (let i = 0; i < lines.length; i += 1) {
+    if (/^\s*import\b/.test(lines[i])) lastImport = i;
+  }
+  if (lastImport === -1) return `${block}\n${source}`;
+  lines.splice(lastImport + 1, 0, block);
+  return lines.join('\n');
+}
+
+/**
+ * Find the parenthesized expression of the FIRST `return (` and return its inner
+ * span [start,end) (exclusive of the wrapping parens). null when the return is
+ * not the safe `return ( … )` shape we auto-wrap.
+ */
+function findReturnParenSpan(source) {
+  const m = /return\s*\(/.exec(source);
+  if (!m) return null;
+  const open = m.index + m[0].length - 1; // index of '('
+  let depth = 0;
+  for (let i = open; i < source.length; i += 1) {
+    const ch = source[i];
+    if (ch === '(') depth += 1;
+    else if (ch === ')') {
+      depth -= 1;
+      if (depth === 0) return { innerStart: open + 1, innerEnd: i, openIdx: open, closeIdx: i };
+    }
+  }
+  return null;
+}
+
+/** Detect indentation (spaces) of the line containing index. */
+function indentAt(source, index) {
+  const lineStart = source.lastIndexOf('\n', index - 1) + 1;
+  const m = /^[ \t]*/.exec(source.slice(lineStart));
+  return m ? m[0] : '';
+}
+
+/**
+ * Produce the wired layout source, or null when the layout is not auto-wrappable.
+ */
+function buildWiredLayout(source, manifestSpecifier) {
+  const span = findReturnParenSpan(source);
+  if (!span) return null;
+  const inner = source.slice(span.innerStart, span.innerEnd);
+  const baseIndent = indentAt(source, span.openIdx);
+  const innerIndent = `${baseIndent}  `;
+
+  // Re-indent the existing tree one level deeper so it nests cleanly.
+  const nested = inner
+    .replace(/^\n/, '')
+    .split('\n')
+    .map((l) => (l.trim() ? `  ${l}` : l))
+    .join('\n');
+
+  const wrapped =
+    `\n${innerIndent}${ORB_START}\n` +
+    `${innerIndent}<FiodosExpoAgent manifest={fyodosManifest as never}>\n` +
+    `${nested}\n` +
+    `${innerIndent}</FiodosExpoAgent>\n` +
+    `${innerIndent}${ORB_END}\n${baseIndent}`;
+
+  const withWrap = source.slice(0, span.innerStart) + wrapped + source.slice(span.innerEnd);
+
+  const importBlock =
+    `${IMPORT_START}\n` +
+    `import { FiodosExpoAgent } from '@fiodos/react-native/expo';\n` +
+    `import fyodosManifest from '${manifestSpecifier}';\n` +
+    `${IMPORT_END}`;
+
+  return insertImportsAfterLastImport(withWrap, importBlock);
+}
+
+/** The copy-paste snippet shown when we can't safely auto-wrap. */
+function mountSnippet(manifestSpecifier) {
+  return (
+    `import { FiodosExpoAgent } from '@fiodos/react-native/expo';\n` +
+    `import fyodosManifest from '${manifestSpecifier}';\n\n` +
+    `// Wrap your root layout's returned tree:\n` +
+    `<FiodosExpoAgent manifest={fyodosManifest as never}>\n` +
+    `  {/* your existing <Stack/> / <Slot/> tree */}\n` +
+    `</FiodosExpoAgent>`
+  );
+}
+
+function printSnippet(colors, layoutRel, manifestSpecifier, reason) {
+  const { blue, cyan, dim, reset } = colors;
+  console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}add the orb to ${layoutRel || 'app/_layout.tsx'}${reason ? ` (${reason})` : ''}:${reset}`);
+  console.error(mountSnippet(manifestSpecifier));
+  console.error(`${dim}Then re-run analyze — the mount becomes automatic once the layout matches.${reset}\n`);
+}
+
+/**
+ * Auto-mount the orb into an Expo Router app.
+ * @returns {{status:'added'|'already'|'printed'|'skipped', file?:string, reason?:string}}
+ */
+function wireReactNativeOrb(appRoot, { manifest, colors = {}, noWire = false } = {}) {
+  const layout = findRootLayout(appRoot);
+  const manifestSpecifier = layout
+    ? manifestImportSpecifier(layout.abs, appRoot)
+    : './fyodos/manifest.json';
+
+  if (!layout) {
+    if (!noWire && manifest) writeManifestFile(appRoot, manifest);
+    printSnippet(colors, null, manifestSpecifier, 'no Expo Router app/_layout found');
+    return { status: 'printed', reason: 'no-layout' };
+  }
+
+  let source;
+  try {
+    source = fs.readFileSync(layout.abs, 'utf8');
+  } catch (e) {
+    return { status: 'skipped', reason: `read-failed: ${e.message}` };
+  }
+
+  if (source.includes('FiodosExpoAgent') || source.includes('FYODOS:ORB')) {
+    if (!noWire && manifest) writeManifestFile(appRoot, manifest);
+    return { status: 'already', file: layout.rel };
+  }
+
+  if (noWire) return { status: 'skipped', reason: 'no-wire' };
+
+  if (manifest) writeManifestFile(appRoot, manifest);
+  const wired = buildWiredLayout(source, manifestSpecifier);
+  if (!wired) {
+    printSnippet(colors, layout.rel, manifestSpecifier, "layout has no plain `return ( … )`");
+    return { status: 'printed', file: layout.rel, reason: 'unrecognized-layout' };
+  }
+
+  try {
+    fs.writeFileSync(layout.abs, wired);
+  } catch (e) {
+    return { status: 'skipped', reason: `write-failed: ${e.message}` };
+  }
+  return { status: 'added', file: layout.rel };
+}
+
+function reportReactNativeWire(result, colors = {}, { quiet = false } = {}) {
+  const { blue, cyan, dim, reset } = colors;
+  if (!result) return;
+  if (result.status === 'added') {
+    console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · orb mounted in ${result.file}`);
+  } else if (result.status === 'already' && !quiet) {
+    console.error(`\n${cyan}◉${reset} ${blue}Fiodos${reset} · ${dim}orb already mounted in ${result.file}${reset}`);
+  }
+}
+
+module.exports = {
+  wireReactNativeOrb,
+  reportReactNativeWire,
+  // exported for tests
+  buildWiredLayout,
+  findReturnParenSpan,
+  writeManifestFile,
+  manifestImportSpecifier,
+  findRootLayout,
+};

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,
@@ -173,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) {
@@ -252,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);
   }
@@ -313,7 +360,12 @@ 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);
@@ -348,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.`);

package/src/writeEnv.js

@@ -60,6 +60,18 @@ function resolveEnvPlan(appRoot) {
   if (deps['@angular/core'] || has('angular.json')) {
     return { framework: 'angular', file: null, candidates: [], keyVar: null, urlVar: null };
   }
+  // Expo / React Native: the orb reads EXPO_PUBLIC_* (Expo inlines these at
+  // build time and exposes them via process.env). A plain `.env` at the app root
+  // is the convention; we still ensure it is git-ignored like any secret file.
+  if (deps.expo || deps['expo-router'] || deps['react-native']) {
+    return {
+      framework: 'expo',
+      file: '.env',
+      candidates: ['.env.local', '.env.development.local', '.env.development', '.env'],
+      keyVar: 'EXPO_PUBLIC_FYODOS_API_KEY',
+      urlVar: 'EXPO_PUBLIC_FYODOS_API_URL',
+    };
+  }
   if (
     deps['@sveltejs/kit'] ||
     deps.svelte ||