@fiodos/cli 0.1.4 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.4",
+  "version": "0.1.7",
   "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

@@ -96,9 +96,9 @@ const PLATFORM_GUIDES = {
     appKindLabel: 'a web app (React, Next.js, Vite, react-router, or similar)',
     screenWord: 'page/view/route',
     routeHintLine:
-      'No reliable static route list is available for web apps, so infer routes/views from the router setup, page/route components, and navigation calls (react-router <Route>, Next.js pages, navigate()/<Link>). Routes you propose are NOT statically verified, so only include ones you can actually see in the code.',
+      'No reliable static route list is available for web apps, so infer routes/views from the router setup, page/route components, and navigation calls (react-router <Route>, Next.js pages, navigate()/<Link>). Routes you propose are NOT statically verified, so only include ones you can actually see in the code below.',
     actionHintLine:
-      'Actions are functions wired to UI: handlers inside components, store/context actions (Zustand, Redux, React Context), or service functions. Set "handler" to that real function name exactly.',
+      'Actions are functions wired to UI IN THE SOURCE FILES PROVIDED BELOW: handlers inside components, store/context actions (Zustand, Redux, React Context), or service functions. Set "handler" to that real function name exactly. CRITICAL: the manifest is for THIS web deployment only — do NOT include routes or actions from mobile/native code that is not in the file list (even if you infer it exists elsewhere in the monorepo).',
   },
   mobile: {
     appKindLabel: 'a mobile app (Expo / React Native)',

package/src/collect.js

@@ -21,7 +21,12 @@ const path = require('path');
 const PROFILES = {
   web: {
     exts: ['.ts', '.tsx', '.js', '.jsx', '.vue', '.svelte'],
-    skipDirs: ['node_modules', 'assets', '.git', 'dist', 'build', '.expo', 'android', 'ios', 'coverage', '.next', 'web-build'],
+    skipDirs: [
+      'node_modules', 'assets', '.git', 'dist', 'build', '.expo', 'android', 'ios', 'coverage',
+      '.next', 'web-build',
+      // Monorepo siblings: never mix mobile/native code into a web analysis.
+      'mobile', 'native', 'flutter', 'react-native', 'expo',
+    ],
   },
   mobile: {
     exts: ['.ts', '.tsx', '.js', '.jsx'],

package/src/index.js

@@ -31,7 +31,8 @@
  *   After analysis, a web target is OFFERED automatic wiring of <FiodosAgent/>
  *   into the app's root layout. It asks before editing your code; on "no" (or a
  *   non-interactive shell) it prints the ready-to-paste snippet instead.
- *     --yes          accept the wiring/env without the prompt (CI / express)
+ *     --yes          accept orb/handler wiring without prompts (CI / express)
+ *     --write-env-yes write the API key to .env without asking (CI only)
  *     --no-wire      skip wiring entirely (analysis/publish unaffected)
  *     --no-write-env skip the offer to align the app's .env with the published
  *                    key/URL (see below)
@@ -39,10 +40,11 @@
  * Avoiding the silent "orb fetches the wrong backend" failure:
  *   After --publish the CLI (1) re-fetches the manifest with the SAME key+URL to
  *   confirm the orb will find it, printing the exact key/URL your app must use,
- *   and (2) on web, OFFERS to write that key/URL into the app's env file
- *   (.env.local for Next, .env for Vite) so the runtime matches what you
- *   published. It never overwrites a differing value silently — it warns and
- *   asks first. Disable with --no-write-env.
+ *   and (2) on web, ASKS at the END whether to write that key/URL into the
+ *   app's env file (.env.local for Next, .env for Vite). If you say yes it
+ *   writes; if you say no it prints the exact file path and lines to add.
+ *   Independent of --yes (which only skips orb/handler prompts). CI: --write-env-yes.
+ *   Disable entirely with --no-write-env.
  *
  * AI key — HYBRID model:
  *   DEFAULT (hosted): the AI analysis runs on the Fiodos backend with FIODOS'S
@@ -88,11 +90,12 @@ loadEnv();
 
 const { scanRoutes } = require('./routes');
 const { collectFiles } = require('./collect');
+const { resolveAnalysisRoot } = require('./resolveAnalysisRoot');
 const { analyzeWithAI, correctActionWiring, DEFAULT_MODEL, resolveModel } = require('./aiAnalyze');
 const { verifyManifest } = require('./verify');
 const { wireWebOrb, reportWireResult } = require('./wireWeb');
 const { wireHandlers, reportHandlerResult } = require('./wireHandlers');
-const { offerWriteEnv } = require('./writeEnv');
+const { offerWriteEnv, printEnvManualReminder } = require('./writeEnv');
 
 function arg(flag, fallback) {
   const i = process.argv.indexOf(flag);
@@ -187,7 +190,8 @@ async function main() {
   // Default output dir lives in the OS temp dir, NOT inside the installed
   // package (when run via npx, __dirname is under node_modules and writing
   // there pollutes the package). Operators can still override with --out.
-  const safeName = path.basename(path.resolve(appRoot)).replace(/[^a-z0-9_-]/gi, '_') || 'app';
+  const inputRoot = path.resolve(appRoot);
+  const safeName = path.basename(inputRoot).replace(/[^a-z0-9_-]/gi, '_') || 'app';
   const outDir = arg('--out', path.join(os.tmpdir(), 'fiodos', 'analysis', safeName));
   // Model precedence: explicit --model (operator override) > backend plan model
   // (resolved below from the analysis-quota pre-check) > DEFAULT_MODEL fallback.
@@ -197,30 +201,47 @@ async function main() {
   const useLLM = !process.argv.includes('--no-llm');
   fs.mkdirSync(outDir, { recursive: true });
 
-  // ── 1. Static route scan (cheap facts; also the route verifier's ground truth)
-  // Platform: auto-detected from the presence of an expo-router app/ dir, or
-  // forced with --platform web|mobile. Web apps have no static route ground
-  // truth, so the AI proposes routes and we keep them unverified (honest flag).
-  const { appDir, routes: scannedRoutes } = scanRoutes(appRoot);
   const platformArg = (arg('--platform', '') || '').toLowerCase();
   const KNOWN_PLATFORMS = ['web', 'mobile', 'flutter', 'ios', 'android'];
-  const platform = KNOWN_PLATFORMS.includes(platformArg)
-    ? platformArg
-    : detectPlatform(appRoot, appDir);
+  const forcedPlatform = KNOWN_PLATFORMS.includes(platformArg) ? platformArg : null;
+
+  // ── 1. Static route scan (cheap facts; also the route verifier's ground truth)
+  // Platform: auto-detected from package.json / native manifests, or forced with
+  // --platform. Web apps have no static route ground truth, so the AI proposes
+  // routes and we keep them unverified (honest flag).
+  const { appDir, routes: scannedRoutes } = scanRoutes(inputRoot);
+  const platform = forcedPlatform ?? detectPlatform(inputRoot, appDir);
+
+  // Monorepos: scope analysis to the sub-app for this platform (e.g. frontend/
+  // for Next, mobile/ for Expo) so the web orb never inherits mobile actions.
+  const explicitAnalysisRoot = arg('--analysis-root', '');
+  const scope = explicitAnalysisRoot
+    ? { root: path.resolve(explicitAnalysisRoot), scoped: true, reason: '--analysis-root' }
+    : resolveAnalysisRoot(inputRoot, platform);
+  const analysisRoot = scope.root;
+  if (scope.scoped) {
+    const rel = path.relative(inputRoot, analysisRoot) || '.';
+    logDev(
+      `Scoped to ${rel} (${platform} app) — analyzing this folder only, not the whole repo.`,
+    );
+    logDev(`[scope] input=${inputRoot} analysis=${analysisRoot} reason=${scope.reason}`);
+  }
+
+  const { appDir: scopedAppDir, routes: scopedRoutes } = scanRoutes(analysisRoot);
   // The expo-router filesystem scan ONLY describes a mobile app. A Next.js App
   // Router web app also has an app/ dir, so the scan would otherwise produce
   // bogus "routes" and misclassify the project; for web we ignore it and let
   // the AI propose routes (the documented web contract).
   // Only Expo/RN ('mobile') has a static route ground truth. Web AND the native
   // platforms (flutter/ios/android) have the AI infer routes (kept unverified).
-  const routes = platform === 'mobile' ? scannedRoutes : [];
+  const routes = platform === 'mobile' ? scopedRoutes : [];
   const verifyRoutes = platform === 'mobile' && routes.length > 0;
-  const appMeta = readAppMeta(appRoot);
+  const appMeta = readAppMeta(analysisRoot);
   logDev(`[static] platform=${platform} routes=${routes.length}` +
     (platform === 'web' ? ' (web: routes inferred by AI, not statically verified)' : ''));
 
   // ── 2. Collect source files (rule-based, budget-aware) ────────────────────
-  const { included, omitted, estimatedTokens } = collectFiles(appRoot, { maxInputTokens, platform });
+  const { included, omitted, estimatedTokens } = collectFiles(analysisRoot, { maxInputTokens, platform });
   fs.writeFileSync(path.join(outDir, 'files-sent.json'), JSON.stringify({
     included: included.map((f) => f.rel),
     omitted,
@@ -244,14 +265,14 @@ async function main() {
     // is not acceptable for this app.
     ({ manifest, provenance } = routesOnlyManifest(appMeta, routes));
     logDev('[no-llm] static-only manifest (routes only, no actions)');
-    logUser(`Static analysis complete — ${manifest.routes.length} routes`);
+    logUser('Static analysis complete');
   } else {
     // Hybrid AI-key model. DEFAULT: hosted analysis via the Fiodos backend
     // proxy (Fiodos's AI key, no key needed by the developer). With
     // --own-ai-key the analysis runs locally against the developer's own
     // provider key (privacy path: source code goes straight to the AI and
     // never reaches Fiodos). --no-llm (handled above) sends no code anywhere.
-    loadAppEnv(path.resolve(appRoot));
+    loadAppEnv(analysisRoot);
     const { apiKey, apiUrl } = resolveApiTarget();
     const useProxy = !process.argv.includes('--own-ai-key');
 
@@ -304,7 +325,7 @@ async function main() {
     const droppedRoutes = provenance.routes.filter((r) => !r.included).length;
     logDev(`[verify] kept routes=${manifest.routes.length} actions=${manifest.actions.length}` +
       ` | dropped: ${droppedRoutes} routes, ${droppedActions} actions (unproven evidence)`);
-    logUser(`Analysis complete — ${manifest.routes.length} routes, ${manifest.actions.length} actions`);
+    logUser('Analysis complete');
 
     fs.writeFileSync(path.join(outDir, 'evidence.json'), JSON.stringify({
       evidence, wiring, uncertain: parsed.uncertain || [],
@@ -353,7 +374,7 @@ async function main() {
   logDev(`[done] output → ${outDir}`);
 
   if (process.argv.includes('--publish')) {
-    loadAppEnv(path.resolve(appRoot));
+    loadAppEnv(analysisRoot);
     await publishManifest(manifest, {
       ...analysisMeta,
       generatedAt: new Date().toISOString(),
@@ -370,35 +391,28 @@ async function main() {
     const { apiKey, apiUrl } = resolveApiTarget();
     const assumeYes = process.argv.includes('--yes') || process.argv.includes('--wire-yes');
     const noWire = process.argv.includes('--no-wire');
+    let envWriteResult = null;
 
-    // ── 5b. Offer to align the app's .env with the published key/URL (consent).
-    // Removes the second manual copy of the key — the root cause of the silent
-    // "orb fetches the wrong backend" failure. Skipped with --no-write-env.
-    if (process.argv.includes('--publish') && !process.argv.includes('--no-write-env')) {
-      try {
-        await offerWriteEnv({
-          appRoot: path.resolve(appRoot),
-          apiKey,
-          apiUrl,
-          defaultApiUrl: DEFAULT_API_URL,
-          assumeYes,
-          log: logUser,
-        });
-      } catch (e) {
-        logDev(`[write-env] skipped: ${e.message}`);
-      }
-    }
     // --no-orb-wire skips ONLY the orb mount (useful to test handler wiring in
     // isolation without modifying the app's entrypoint / package.json).
     if (!process.argv.includes('--no-orb-wire')) {
-      const result = await wireWebOrb(path.resolve(appRoot), {
+      const result = await wireWebOrb(analysisRoot, {
         apiUrl,
         colors: fyodosTermColors(),
         assumeYes,
         noWire,
         runTest: !process.argv.includes('--no-wire-test'),
       });
-      reportWireResult(result, fyodosTermColors());
+      reportWireResult(result, fyodosTermColors(), { quiet: !isVerbose() });
+      // Tell the dashboard the orb is wired — no need to boot localhost for the
+      // onboarding checker to complete.
+      if (
+        process.argv.includes('--publish') &&
+        apiKey &&
+        (result.status === 'added' || result.status === 'already')
+      ) {
+        await postOrbWired({ apiKey, apiUrl, file: result.file || '' });
+      }
     }
 
     // ── 7. Web: SECOND consent — connect detected actions to real app functions.
@@ -417,7 +431,7 @@ async function main() {
           return fixed;
         }
       : null;
-    const handlerResult = await wireHandlers(path.resolve(appRoot), {
+    const handlerResult = await wireHandlers(analysisRoot, {
       manifest,
       evidence,
       wiring,
@@ -425,6 +439,7 @@ async function main() {
       colors: fyodosTermColors(),
       assumeYes,
       noWire,
+      quiet: !isVerbose(),
       runTest: !process.argv.includes('--no-wire-test'),
       revertOnFailure: true,
       testRunner: runPostWireTest,
@@ -432,7 +447,32 @@ async function main() {
       files: included,
       maxAttempts: Number(process.env.FYODOS_WIRE_MAX_ATTEMPTS || 3),
     });
-    reportHandlerResult(handlerResult, fyodosTermColors());
+    reportHandlerResult(handlerResult, fyodosTermColors(), { quiet: !isVerbose() });
+
+    // ── 8. API key in environment (LAST step — always asks; independent of --yes)
+    // --yes only skips orb/handler prompts. --write-env-yes skips this one (CI).
+    // If the developer declines, we show a copy-paste reminder here at the end.
+    if (process.argv.includes('--publish') && !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 &&
+          (envWriteResult.status === 'declined by user' || envWriteResult.status === 'manual')
+        ) {
+          printEnvManualReminder(envWriteResult.writePlan, { logUser, logDev });
+        }
+      } catch (e) {
+        logDev(`[write-env] skipped: ${e.message}`);
+      }
+    }
   }
 }
 
@@ -686,17 +726,11 @@ async function publishManifest(manifest, meta, analysisToken = null) {
     process.exit(1);
   }
   const body = await res.json();
-  logUser(`Published to your project — ${body.routes} routes, ${body.actions} actions`);
+  logUser('Published to your project');
   logDev(`[publish] OK — ${body.routes} routes, ${body.actions} actions received at ${body.receivedAt}`);
 
-  // ── Self-check: confirm the orb will actually FIND this manifest ───────────
-  // Re-fetch it the way the SDK does at runtime (GET /v1/client/manifest with
-  // the SAME key + URL). This catches the silent-failure setup BEFORE the
-  // developer is left wondering why the orb never appears, and prints the exact
-  // key/URL their app must use so they can compare with their .env.
+  // Self-check: confirm the orb will find this manifest (silent unless --verbose).
   await verifyOrbCanFetch({ apiKey, apiUrl });
-
-  logUser('Open the dashboard → Agent settings → "Reload analysis" to review');
 }
 
 /**
@@ -705,6 +739,23 @@ async function publishManifest(manifest, meta, analysisToken = null) {
  * and URL their running app must use. Never hard-fails the publish (the publish
  * already succeeded); a failed re-fetch is surfaced as an actionable warning.
  */
+async function postOrbWired({ apiKey, apiUrl, file }) {
+  if (!apiKey) return;
+  try {
+    const res = await fetch(`${apiUrl}/v1/developer/orb-wired`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
+      body: JSON.stringify({ file: file || '', platform: 'web' }),
+    });
+    if (res.ok) {
+      logDev(`[orb-wired] install proof recorded (${file || 'web'})`);
+    } else {
+      logDev(`[orb-wired] could not record install proof: HTTP ${res.status}`);
+    }
+  } catch (e) {
+    logDev(`[orb-wired] skipped: ${e.message || e}`);
+  }
+}
 async function verifyOrbCanFetch({ apiKey, apiUrl }) {
   try {
     const res = await fetch(`${apiUrl}/v1/client/manifest`, {
@@ -714,27 +765,15 @@ async function verifyOrbCanFetch({ apiKey, apiUrl }) {
     if (res.ok) {
       const data = await res.json().catch(() => null);
       if (data && data.manifest) {
-        logUser(
-          `✓ Verified: your orb will find this manifest using API key ${apiKey.slice(0, 12)}… ` +
-            `against ${apiUrl}.`,
-        );
-        logUser(
-          'Make sure your app uses this SAME key and URL in its .env ' +
-            '(NEXT_PUBLIC_FYODOS_API_KEY / VITE_FYODOS_API_KEY, and the API URL).',
+        logDev(
+          `[verify] manifest reachable with key ${apiKey.slice(0, 12)}… against ${apiUrl}`,
         );
         return true;
       }
     }
-    logUser(
-      `⚠︎ Published, but could not re-read the manifest from ${apiUrl} (HTTP ${res.status}). ` +
-        'Check that your app uses this same key and URL.',
-    );
+    logDev(`[verify] published but re-fetch failed: HTTP ${res.status}`);
   } catch (e) {
     logDev(`[verify] re-fetch failed: ${e.message}`);
-    logUser(
-      `⚠︎ Published, but could not reach ${apiUrl} to verify. ` +
-        'Confirm your app points to this same URL and key.',
-    );
   }
   return false;
 }

package/src/resolveAnalysisRoot.js

@@ -0,0 +1,125 @@
+/**
+ * resolveAnalysisRoot — pick the folder the CLI should actually analyze.
+ *
+ * Monorepos often contain BOTH a web app (Next/Vite) and a mobile app
+ * (Expo/RN) under one git root. Running `analyze .` from the repo root makes
+ * the AI read mobile screens too, so the web orb gets actions that do not
+ * exist on the website. When we can identify a single sub-app for the target
+ * platform, we scope collection/wiring to THAT folder only.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SKIP_SCAN = new Set([
+  'node_modules', '.git', 'dist', 'build', '.next', 'coverage', 'android', 'ios',
+  '.expo', 'web-build', '.venv', 'vendor', 'target', '.gradle', '.dart_tool',
+]);
+
+/** Conventional subfolder names — checked first (higher confidence). */
+const WEB_ROOT_NAMES = ['frontend', 'web', 'www', 'client', 'apps/web', 'packages/web'];
+const MOBILE_ROOT_NAMES = ['mobile', 'app', 'apps/mobile', 'apps/app', 'packages/mobile', 'native'];
+
+function readDeps(pkgPath) {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  } catch {
+    return null;
+  }
+}
+
+function hasWebDeps(deps) {
+  if (!deps) return false;
+  return Boolean(
+    deps.next || deps.vite || deps['@vitejs/plugin-react'] || deps['react-scripts'] ||
+    deps['@angular/core'] || deps['@angular-devkit/build-angular'] ||
+    deps['@sveltejs/kit'] || deps.svelte || deps.vue || deps['@vue/cli-service'],
+  );
+}
+
+function hasMobileDeps(deps) {
+  if (!deps) return false;
+  return Boolean(deps.expo || deps['expo-router'] || deps['react-native']);
+}
+
+function platformDepsMatch(deps, platform) {
+  if (!deps) return false;
+  if (platform === 'web') return hasWebDeps(deps) && !hasMobileDeps(deps);
+  if (platform === 'mobile') return hasMobileDeps(deps) && !hasWebDeps(deps);
+  return false;
+}
+
+function tryCandidate(appRoot, rel, platform, score) {
+  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 };
+}
+
+/**
+ * @returns {{ root: string, scoped: boolean, reason: string }}
+ */
+function resolveAnalysisRoot(appRoot, platform) {
+  const abs = path.resolve(appRoot);
+  const rootDeps = readDeps(path.join(abs, 'package.json'));
+
+  // Root IS the target app (single-package repo).
+  if (platformDepsMatch(rootDeps, platform)) {
+    return { root: abs, scoped: false, reason: 'root package.json' };
+  }
+
+  const candidates = [];
+
+  const preferred = platform === 'web' ? WEB_ROOT_NAMES : MOBILE_ROOT_NAMES;
+  for (const name of preferred) {
+    const hit = tryCandidate(abs, name, platform, 20);
+    if (hit) candidates.push(hit);
+  }
+
+  // One level of immediate subdirs (frontend/, mobile/, apps/*, packages/*).
+  let entries = [];
+  try {
+    entries = fs.readdirSync(abs, { withFileTypes: true });
+  } catch {
+    return { root: abs, scoped: false, reason: 'unreadable root' };
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory() || SKIP_SCAN.has(entry.name)) continue;
+    const hit = tryCandidate(abs, entry.name, platform, 10);
+    if (hit) candidates.push(hit);
+
+    // apps/web, packages/web, etc.
+    const nestedRoot = path.join(abs, entry.name);
+    let nested = [];
+    try {
+      nested = fs.readdirSync(nestedRoot, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const sub of nested) {
+      if (!sub.isDirectory() || SKIP_SCAN.has(sub.name)) continue;
+      const rel = path.join(entry.name, sub.name);
+      const deep = tryCandidate(abs, rel, platform, 8);
+      if (deep) candidates.push(deep);
+    }
+  }
+
+  if (!candidates.length) {
+    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);
+  const best = candidates[0];
+  return {
+    root: best.root,
+    scoped: best.root !== abs,
+    reason: best.reason,
+  };
+}
+
+module.exports = { resolveAnalysisRoot, hasWebDeps, hasMobileDeps };

package/src/wireHandlers.js

@@ -1360,10 +1360,10 @@ async function runAutoCorrectionLoop(ctx) {
   const {
     appRoot, fyodosDirRel, fyodosDirAbs, manifest, evidence, wiringMap,
     ts, esm, ext, testRunner, corrector, files, framework,
-    maxAttempts = 3, tag, dim, reset, registryRel,
+    maxAttempts = 3, tag, dim, reset, registryRel, quiet = false,
   } = ctx;
 
-  const log = (m) => console.error(`${tag} · ${dim || ''}${m}${reset || ''}`);
+  const log = quiet ? () => {} : (m) => console.error(`${tag} · ${dim || ''}${m}${reset || ''}`);
   log('Verifying and auto-correcting each action (may take a while)…');
   const baseline = await testRunner(appRoot, { framework });
 
@@ -1455,6 +1455,7 @@ async function wireHandlers(appRoot, opts = {}) {
     colors = {},
     assumeYes = false,
     noWire = false,
+    quiet = false,
     framework = 'web',
     appName,
     registryExt: registryExtOpt,
@@ -1516,13 +1517,15 @@ async function wireHandlers(appRoot, opts = {}) {
   //    to consent and let the loop decide what ends up wired.
   const loopEnabled = typeof corrector === 'function' && runTest && testRunner;
   if (!plan.auto.length && !loopEnabled) {
-    console.error(
-      `\n${tag} · ${dim || ''}Prepared the action wiring, but none of the ` +
-        `${plan.manual.length} action(s) can be connected with confidence.${reset || ''}`,
-    );
-    console.error(
-      `${tag} · See what is needed and how to do it by hand in: ${docRel}`,
-    );
+    if (!quiet) {
+      console.error(
+        `\n${tag} · ${dim || ''}Prepared the action wiring, but none of the ` +
+          `${plan.manual.length} action(s) can be connected with confidence.${reset || ''}`,
+      );
+      console.error(
+        `${tag} · See what is needed and how to do it by hand in: ${docRel}`,
+      );
+    }
     return { status: 'manual-only', docPath: docAbs, autoCount: 0, manualCount: plan.manual.length, plan };
   }
 
@@ -1538,29 +1541,33 @@ async function wireHandlers(appRoot, opts = {}) {
     `${tag} · Apply these changes after reviewing? [yes/no] `;
 
   if (!assumeYes && !process.stdin.isTTY) {
-    console.error(prompt.trimEnd());
-    console.error(
-      `${tag} · ${dim || ''}Non-interactive terminal: leaving your code untouched. The document ` +
-        `is at ${docRel}. Re-run with --wire-yes to apply it.${reset || ''}`,
-    );
+    if (!quiet) {
+      console.error(prompt.trimEnd());
+      console.error(
+        `${tag} · ${dim || ''}Non-interactive terminal: leaving your code untouched. The document ` +
+          `is at ${docRel}. Re-run with --wire-yes to apply it.${reset || ''}`,
+      );
+    }
     return { status: 'declined-noninteractive', docPath: docAbs, autoCount: plan.auto.length, manualCount: plan.manual.length, plan };
   }
 
   const yes = assumeYes || (await askYesNo(prompt));
   if (!yes) {
-    console.error(
-      `${tag} · ${dim || ''}Leaving your code untouched. The document stays at ${docRel} ` +
-        `in case you want to wire it by hand or re-run with --wire-yes.${reset || ''}`,
-    );
+    if (!quiet) {
+      console.error(
+        `${tag} · ${dim || ''}Leaving your code untouched. The document stays at ${docRel} ` +
+          `in case you want to wire it by hand or re-run with --wire-yes.${reset || ''}`,
+      );
+    }
     return { status: 'declined', docPath: docAbs, autoCount: plan.auto.length, manualCount: plan.manual.length, plan };
   }
 
   // 4) Baseline: BEFORE touching anything, check whether the app already builds.
-  //    This lets us tell "we broke it" (revert) from "it was already broken"
-  //    (don't revert a good wiring over a pre-existing failure).
   let baseline = null;
   if (runTest && testRunner) {
-    console.error(`${tag} · ${dim || ''}Checking the build baseline BEFORE wiring…${reset || ''}`);
+    if (!quiet) {
+      console.error(`${tag} · ${dim || ''}Checking the build baseline BEFORE wiring…${reset || ''}`);
+    }
     try {
       baseline = await testRunner(appRoot, { framework });
     } catch (err) {
@@ -1579,7 +1586,7 @@ async function wireHandlers(appRoot, opts = {}) {
     const loop = await runAutoCorrectionLoop({
       appRoot, fyodosDirRel, fyodosDirAbs, manifest, evidence, wiringMap,
       ts, esm, ext, testRunner, corrector, files, framework, maxAttempts,
-      tag, dim, reset, registryRel, baseline,
+      tag, dim, reset, registryRel, baseline, quiet,
     });
 
     const finalAuto = loop.ready;
@@ -1692,7 +1699,9 @@ async function wireHandlers(appRoot, opts = {}) {
     if (baseline && baseline.ok === false && baseline.stage !== 'skipped-no-deps') {
       return { status: 'applied-untested', ...baseResult, test: baseline, preexistingFailure: true };
     }
-    console.error(`${tag} · ${dim || ''}Checking the app still builds after wiring…${reset || ''}`);
+    if (!quiet) {
+      console.error(`${tag} · ${dim || ''}Checking the app still builds after wiring…${reset || ''}`);
+    }
     let test;
     try {
       test = await testRunner(appRoot, { framework });
@@ -1710,50 +1719,26 @@ async function wireHandlers(appRoot, opts = {}) {
   return { status: 'applied', ...baseResult };
 }
 
-function reportHandlerResult(result, colors = {}) {
+function reportHandlerResult(result, colors = {}, opts = {}) {
+  const quiet = opts.quiet !== false;
   if (!result) return;
   const { blue, cyan, dim, reset } = colors;
   const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
   switch (result.status) {
     case 'applied':
-    case 'applied-untested': {
-      const rel = result.registryRel || result.registryFile;
-      console.error(`${tag} · ✓ Handler wiring applied → ${rel} (${result.autoCount} action(s)).`);
-      if (Array.isArray(result.verification) && result.verification.length) {
-        const ready = result.verification.filter((v) => v.status === 'ready');
-        const corrected = ready.filter((v) => v.attempts > 1).length;
-        const firstTry = ready.length - corrected;
-        const eff = ready.filter((v) => v.level === 'effect').length;
-        console.error(`${tag} · ${dim || ''}Verification: ${ready.length} action(s) ready (${firstTry} on first try, ${corrected} after auto-correction, ${eff} with real effect confirmed).${reset || ''}`);
-      }
-      if (result.editedFiles && result.editedFiles.length) {
-        console.error(`${tag} · ${dim || ''}Bridges added (reversible) in: ${result.editedFiles.join(', ')}.${reset || ''}`);
-      }
-      if (Array.isArray(result.dropped) && result.dropped.length) {
-        console.error(`${tag} · ${dim || ''}${result.dropped.length} action(s) could NOT be wired after retries (reverted, see the document): ${result.dropped.map((d) => d.intent).join(', ')}.${reset || ''}`);
-      } else if (result.manualCount) {
-        console.error(`${tag} · ${dim || ''}${result.manualCount} action(s) left for review (see the document).${reset || ''}`);
-      }
-      if (result.test && result.test.ok) {
-        console.error(`${tag} · ✓ Post-wiring build check OK (${result.test.stage}).`);
-      } else if (result.preexistingFailure) {
-        console.error(`${tag} · ${dim || ''}Note: your app was ALREADY not building BEFORE wiring (${result.test && result.test.stage}); not caused by Fiodos, so the wiring is kept but cannot be build-verified.${reset || ''}`);
-      } else if (result.status === 'applied-untested') {
-        console.error(`${tag} · ${dim || ''}Note: could not verify the build (${result.test && result.test.stage}); please check it.${reset || ''}`);
-      }
-      console.error(`${tag} · ${dim || ''}Enable it by passing registries={fyodosGeneratedRegistries} to <FiodosAgent/> (snippet in the document).${reset || ''}`);
+    case 'applied-untested':
+      if (quiet) return;
       break;
-    }
     case 'reverted':
       console.error(`${tag} · ✗ Post-wiring build check failed (${result.test && result.test.stage}) — reverted all changes, your app is untouched.`);
       console.error(`${tag} · ${dim || ''}Details in the document; nothing was modified in your code.${reset || ''}`);
       break;
     case 'manual-only':
+      if (quiet) return;
       console.error(`${tag} · ${dim || ''}Wiring documented; apply it by hand following ${result.docPath}.${reset || ''}`);
       break;
     case 'declined':
     case 'declined-noninteractive':
-      // already reported inline
       break;
     case 'failed':
       console.error(`${tag} · ✗ Could not write the handler registry: ${result.error && result.error.message}`);

package/src/wireWeb.js

@@ -222,7 +222,9 @@ async function wireWebOrb(appRoot, opts = {}) {
     return { status: 'printed', reason: plan.reason };
   }
 
-  printMountPreview(plan, colors);
+  if (!assumeYes) {
+    printMountPreview(plan, colors);
+  }
 
   const yes = assumeYes || (await askYesNo(
     `${colors.cyan || ''}◉${colors.reset || ''} About to add the orb to ${plan.rel}. Proceed? [y/N] `,
@@ -286,22 +288,15 @@ async function wireWebOrb(appRoot, opts = {}) {
   }
 }
 
-function reportWireResult(result, colors = {}) {
+function reportWireResult(result, colors = {}, opts = {}) {
+  const quiet = opts.quiet !== false;
+  if (!result) return;
   const { blue, cyan, dim, reset } = colors;
   const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
   switch (result.status) {
     case 'added':
-      console.error(`${tag} · ✓ orb added to ${result.file}. Start your web app (e.g. \`npm run dev\`) to see it.`);
-      if (result.preexistingFailure) {
-        console.error(`${tag} · ${dim || ''}Note: your app was ALREADY not building before the orb was added (${result.test && result.test.stage}); not caused by Fiodos — the orb is kept so it appears once your build is fixed.${reset || ''}`);
-      } else if (result.test && result.test.stage === 'skipped-no-deps') {
-        console.error(`${tag} · ${dim || ''}build not verified (no node_modules) — run npm install && npm run build locally.${reset || ''}`);
-      } else if (result.test && result.test.ok) {
-        console.error(`${tag} · ✓ ${result.test.command} passed after mount.`);
-      }
-      break;
     case 'already':
-      console.error(`${tag} · ✓ orb already mounted in ${result.file}. Nothing to do.`);
+      if (quiet) return;
       break;
     case 'declined':
       console.error(`${tag} · ${dim || ''}did not modify your code. Paste the snippet above to mount the orb.${reset || ''}`);

package/src/writeEnv.js

@@ -1,19 +1,10 @@
 /**
- * writeEnv — optional, consent-based convenience that ties the app's RUNTIME
- * key/URL to the SAME key/URL the CLI just published with.
+ * writeEnv — consent-based API key / URL alignment for the app's environment.
  *
- * The #1 silent-failure cause is a mismatch: you publish with key A against
- * production, but your app runs with key B against localhost, so the orb fetches
- * its manifest from the wrong place, finds nothing, and renders invisibly. This
- * removes the second manual copy of the key by offering to write it into the
- * correct env file for the detected framework.
- *
- * SAFEGUARDS (mirrors the handler-wiring philosophy — never act blindly):
- *  - Never overwrites silently: if the var exists and DIFFERS, it warns and asks.
- *  - Always asks for consent (unless --yes), showing the exact file/var/value.
- *  - Warns to keep the key out of git (suggests .gitignore) for committed files.
- *  - On unknown framework / no package.json / Angular (no .env convention), it
- *    does NOT write — it prints manual instructions instead.
+ * The orb must read the SAME key/URL the CLI published with. We always ASK
+ * before writing (independent of --yes, which only skips orb/handler prompts).
+ * If the developer declines, a copy-paste reminder is shown at the very END of
+ * the run — after analysis, publish, orb mount and handler wiring are done.
  */
 'use strict';
 
@@ -30,12 +21,7 @@ function readJsonSafe(file) {
 }
 
 /**
- * Decide which env files + variable names the detected framework uses. Returns
- * `file: null` when there is no safe .env convention to write (Angular,
- * unknown). `candidates` is the list of env files the framework loads, ordered
- * HIGHEST precedence first — so we can fix the value WHERE THE APP ACTUALLY
- * READS IT instead of writing a second file that may or may not win. `file` is
- * the default file to create when no candidate already defines the vars.
+ * Decide which env files + variable names the detected framework uses.
  */
 function resolveEnvPlan(appRoot) {
   const pkg = readJsonSafe(path.join(appRoot, 'package.json'));
@@ -46,8 +32,6 @@ function resolveEnvPlan(appRoot) {
   const deps = pkg ? { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) } : {};
 
   if (deps.next) {
-    // Next dev precedence (first wins): .env.development.local > .env.local >
-    // .env.development > .env.
     return {
       framework: 'next',
       file: '.env.local',
@@ -57,8 +41,6 @@ function resolveEnvPlan(appRoot) {
     };
   }
   if (deps['@angular/core'] || has('angular.json')) {
-    // Angular has no .env convention (values live in environment.ts), so we
-    // never write a file blindly — the caller prints manual guidance instead.
     return { framework: 'angular', file: null, candidates: [], keyVar: null, urlVar: null };
   }
   if (
@@ -70,8 +52,6 @@ function resolveEnvPlan(appRoot) {
     deps['@vitejs/plugin-react'] ||
     deps['react-scripts']
   ) {
-    // Vite dev precedence (first wins): .env.development.local >
-    // .env.development > .env.local > .env.
     return {
       framework: 'vite',
       file: '.env',
@@ -83,11 +63,6 @@ function resolveEnvPlan(appRoot) {
   return { framework: null, file: null, candidates: [], keyVar: null, urlVar: null };
 }
 
-/**
- * Scan the framework's candidate env files (highest precedence first) for VAR.
- * Returns { file, value } for the first (highest-precedence) file that defines
- * it — i.e. the value the running app actually reads — or null if none do.
- */
 function findEffectiveVar(appRoot, candidates, name) {
   for (const rel of candidates) {
     const filePath = path.join(appRoot, rel);
@@ -99,7 +74,6 @@ function findEffectiveVar(appRoot, candidates, name) {
   return null;
 }
 
-/** Find the value of VAR in the parsed lines, or undefined if not present. */
 function readEnvVar(lines, name) {
   const re = new RegExp(`^\\s*${name}\\s*=(.*)$`);
   for (const line of lines) {
@@ -113,7 +87,6 @@ function stripQuotes(v) {
   return v.replace(/^['"]/, '').replace(/['"]$/, '');
 }
 
-/** Upsert VAR=value: replace the existing line, or append a new one. */
 function upsertEnvVar(lines, name, value) {
   const re = new RegExp(`^\\s*${name}\\s*=`);
   const idx = lines.findIndex((l) => re.test(l));
@@ -159,118 +132,162 @@ function isGitIgnored(appRoot, fileName) {
 }
 
 /**
- * Offer to write key/URL to the app's env file. `log` is the branded logUser.
- * Returns a short status string for the final report.
+ * Compute where the key/URL would go and what would change — no writes, no prompts.
+ * @returns {object|null} null when there is nothing to do (already aligned / no key).
  */
-async function offerWriteEnv({ appRoot, apiKey, apiUrl, defaultApiUrl, assumeYes, log }) {
-  if (!apiKey) return 'skipped (no API key)';
+function computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl) {
+  if (!apiKey) return null;
 
   const plan = resolveEnvPlan(appRoot);
-  if (!plan.file) {
-    if (plan.framework === 'angular') {
-      log(
-        'Angular does not use .env: put these values in src/environments/environment.ts → ' +
-          `fyodosApiKey: '${maskKey(apiKey)}', fyodosApiUrl: '${apiUrl}'`,
-      );
-      return 'manual (angular)';
-    }
-    log(
-      'Could not identify the framework with confidence; add by hand to your .env: ' +
-        `(NEXT_PUBLIC_/VITE_)FYODOS_API_KEY=${maskKey(apiKey)} and the API URL ${apiUrl}`,
-    );
-    return 'manual (unknown framework)';
+  if (!plan.file && plan.framework !== 'angular') {
+    return {
+      kind: 'manual-unknown',
+      framework: plan.framework,
+      keyVar: 'NEXT_PUBLIC_FYODOS_API_KEY or VITE_FYODOS_API_KEY',
+      urlVar: 'NEXT_PUBLIC_FYODOS_API_URL or VITE_FYODOS_API_URL',
+      apiKey,
+      apiUrl,
+    };
+  }
+  if (plan.framework === 'angular') {
+    return {
+      kind: 'manual-angular',
+      file: 'src/environments/environment.ts',
+      apiKey,
+      apiUrl,
+    };
   }
 
-  // Look across ALL the files the framework loads (not just the default one):
-  // the app may already keep its Fiodos vars in .env while we would otherwise
-  // create a separate .env.local — leaving the stale value the orb actually
-  // reads untouched. Fix the value WHERE THE APP READS IT.
   const candidates = plan.candidates && plan.candidates.length ? plan.candidates : [plan.file];
   const effectiveKey = findEffectiveVar(appRoot, candidates, plan.keyVar);
   const effectiveUrl = findEffectiveVar(appRoot, candidates, plan.urlVar);
   const currentKey = effectiveKey ? effectiveKey.value : undefined;
   const currentUrl = effectiveUrl ? effectiveUrl.value : undefined;
-
-  // Write in the highest-precedence file that already defines either var (so the
-  // fix is the value the app loads). If none do, create the framework default.
   const targetRel = (effectiveKey && effectiveKey.file) || (effectiveUrl && effectiveUrl.file) || plan.file;
-  const filePath = path.join(appRoot, targetRel);
-  const exists = fs.existsSync(filePath);
-  const raw = exists ? fs.readFileSync(filePath, 'utf8') : '';
-  const lines = raw.length ? raw.replace(/\n$/, '').split('\n') : [];
-
-  // Only write a URL var when it differs from the public default (the SDK
-  // already defaults to production). But if a STALE url var exists and differs
-  // from what we published against, we must offer to fix it — that is exactly
-  // the localhost-vs-production mismatch that hides the orb.
   const wantUrl = apiUrl && apiUrl !== defaultApiUrl ? apiUrl : null;
   const urlNeedsFix = currentUrl !== undefined && currentUrl !== apiUrl;
-
   const keyMatches = currentKey === apiKey;
   const urlOk = !urlNeedsFix && (wantUrl ? currentUrl === wantUrl : true);
+
   if (keyMatches && urlOk) {
-    log(`✓ Your ${targetRel} already uses the same key/URL as the publication. Nothing to change.`);
-    return 'already aligned';
+    return { kind: 'aligned', targetRel, plan };
   }
 
-  // Build the change description.
-  const changes = [];
-  if (!keyMatches) {
-    changes.push(
-      currentKey === undefined
-        ? `add ${plan.keyVar}=${maskKey(apiKey)}`
-        : `update ${plan.keyVar} (was ${maskKey(currentKey)}) → ${maskKey(apiKey)}`,
+  const envLines = [`${plan.keyVar}=${apiKey}`];
+  if (wantUrl) envLines.push(`${plan.urlVar}=${wantUrl}`);
+  else if (urlNeedsFix) envLines.push(`${plan.urlVar}=${apiUrl}`);
+
+  return {
+    kind: 'writable',
+    plan,
+    targetRel,
+    absPath: path.join(appRoot, targetRel),
+    envLines,
+    keyMatches,
+    urlOk,
+    wantUrl,
+    urlNeedsFix,
+    currentKey,
+    currentUrl,
+    apiKey,
+    apiUrl,
+  };
+}
+
+/** Branded reminder shown at the END when the developer declined the write. */
+function printEnvManualReminder(writePlan, { logUser, logDev }) {
+  if (!writePlan || writePlan.kind === 'aligned') return;
+
+  logUser('Add your API key to your environment file (last step)');
+
+  if (writePlan.kind === 'manual-angular') {
+    console.log(
+      `  Angular: open ${writePlan.file} and set fyodosApiKey / fyodosApiUrl:`,
     );
+    console.log(`    fyodosApiKey: '${writePlan.apiKey}'`);
+    console.log(`    fyodosApiUrl: '${writePlan.apiUrl}'`);
+    return;
   }
-  if (wantUrl && currentUrl !== wantUrl) {
-    changes.push(
-      currentUrl === undefined
-        ? `add ${plan.urlVar}=${wantUrl}`
-        : `update ${plan.urlVar} (was ${currentUrl}) → ${wantUrl}`,
-    );
-  } else if (urlNeedsFix && !wantUrl) {
-    // The app points somewhere (e.g. localhost) but we published against the
-    // public default; the var is misleading. Offer to align it explicitly.
-    changes.push(`update ${plan.urlVar} (was ${currentUrl}) → ${apiUrl}`);
+
+  if (writePlan.kind === 'manual-unknown') {
+    console.log('  Add to your project .env (use NEXT_PUBLIC_ for Next, VITE_ for Vite):');
+    console.log(`    ${writePlan.keyVar}=${writePlan.apiKey}`);
+    if (writePlan.apiUrl && writePlan.apiUrl !== 'https://api.fyodos.com') {
+      console.log(`    ${writePlan.urlVar}=${writePlan.apiUrl}`);
+    }
+    return;
+  }
+
+  const rel = writePlan.targetRel;
+  const displayPath = writePlan.absPath;
+  console.log(`  File: ${displayPath}`);
+  console.log('  Add these lines:');
+  for (const line of writePlan.envLines) {
+    console.log(`    ${line}`);
   }
+  logDev(`[write-env] manual reminder for ${rel}`);
+}
 
-  if (!changes.length) {
-    log(`✓ Your ${targetRel} is already aligned.`);
-    return 'already aligned';
+/**
+ * Ask consent and optionally write. Returns { status, writePlan }.
+ * `assumeYes` comes from --write-env-yes only (NOT global --yes).
+ */
+async function offerWriteEnv({ appRoot, apiKey, apiUrl, defaultApiUrl, assumeYes, log, logDev: devLog }) {
+  const writePlan = computeEnvWritePlan(appRoot, apiKey, apiUrl, defaultApiUrl);
+  if (!writePlan) return { status: 'skipped (no API key)', writePlan: null };
+  if (writePlan.kind === 'aligned') {
+    log(`Your environment already uses the same API key as this project. Nothing to change.`);
+    return { status: 'already aligned', writePlan };
   }
 
-  // Loud warning when we are about to CHANGE an existing, different value.
-  const isOverwrite = (currentKey !== undefined && !keyMatches) || urlNeedsFix;
-  log(
-    `${isOverwrite ? '⚠︎ ' : ''}For the orb to find its manifest, your app should use the SAME ` +
-      `key/URL you just published with. Proposed in ${targetRel}: ${changes.join('; ')}.`,
-  );
+  const targetLabel =
+    writePlan.kind === 'manual-angular'
+      ? writePlan.file
+      : writePlan.kind === 'manual-unknown'
+        ? 'your .env file'
+        : writePlan.targetRel;
 
   let proceed = assumeYes;
   if (!proceed) {
     proceed = await askYesNo(
-      `◉ Fiodos · Write/update ${targetRel} with the published key/URL? [yes/no] `,
+      `◉ Fiodos · Add your API key to ${targetLabel}? [yes/no] `,
     );
   }
+
   if (!proceed) {
-    log(`Left your ${targetRel} untouched. Do it by hand: ${changes.join('; ')}.`);
-    return 'declined by user';
+    return { status: 'declined by user', writePlan };
+  }
+
+  if (writePlan.kind === 'manual-angular' || writePlan.kind === 'manual-unknown') {
+    log('Could not write automatically for this framework — see the reminder at the end.');
+    return { status: 'manual', writePlan };
   }
 
+  const { plan, targetRel, keyMatches, wantUrl, urlNeedsFix, apiKey: key, apiUrl: url } = writePlan;
+  const filePath = writePlan.absPath;
+  const exists = fs.existsSync(filePath);
+  const raw = exists ? fs.readFileSync(filePath, 'utf8') : '';
+  const lines = raw.length ? raw.replace(/\n$/, '').split('\n') : [];
+
   let out = lines.slice();
-  if (!keyMatches) out = upsertEnvVar(out, plan.keyVar, apiKey);
+  if (!keyMatches) out = upsertEnvVar(out, plan.keyVar, key);
   if (wantUrl) {
     out = upsertEnvVar(out, plan.urlVar, wantUrl);
   } else if (urlNeedsFix) {
-    out = upsertEnvVar(out, plan.urlVar, apiUrl);
+    out = upsertEnvVar(out, plan.urlVar, url);
   }
   fs.writeFileSync(filePath, `${out.join('\n')}\n`);
-  log(`✓ ${targetRel} updated (${changes.join('; ')}).`);
+  log(`API key saved to ${targetRel}.`);
 
   if (!isGitIgnored(appRoot, targetRel)) {
-    log(`Reminder: add ${targetRel} to .gitignore so you don't commit your API key.`);
+    devLog(`Reminder: add ${targetRel} to .gitignore so you don't commit your API key.`);
   }
-  return 'written';
+  return { status: 'written', writePlan };
 }
 
-module.exports = { offerWriteEnv, resolveEnvPlan };
+module.exports = {
+  offerWriteEnv,
+  resolveEnvPlan,
+  computeEnvWritePlan,
+  printEnvManualReminder,
+};