@fiodos/cli 0.1.20 → 0.1.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.20",
+  "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/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
@@ -979,6 +1193,7 @@ async function postOrbWired({
   apiKey,
   apiUrl,
   file,
+  platform = 'web',
   actionsStatus = 'pending',
   actionsTotal = 0,
   actionsDone = 0,
@@ -990,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/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/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 ||