@fiodos/cli 0.1.26 → 0.1.29

package/package.json

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

@@ -326,6 +326,34 @@ async function analyzeViaProxy({ apiKey, apiUrl, model, user, task = 'analysis',
       'Or pass --own-ai-key to analyze with your own AI key (code never reaches Fiodos).',
     );
   }
+  // PRE-FLIGHT platform check (analysis only, non-web platforms): the deployed
+  // backend may be OLDER than this CLI and not know the platform yet — its
+  // prompt builder then silently falls back to the generic web prompt and the
+  // resulting manifest misses the platform spec entirely (e.g. Shopify's
+  // execution blocks). The system-prompt endpoint echoes the platform it
+  // resolved, so a stale backend is detectable BEFORE spending any AI tokens.
+  // Fail-open on network/endpoint errors: the post-call echo guard still runs.
+  if (task === 'analysis' && platform && platform !== 'web') {
+    try {
+      const probe = await fetch(
+        `${apiUrl}/v1/developer/analysis/system-prompt?task=analysis&platform=${encodeURIComponent(platform)}`,
+        { headers: { 'x-api-key': apiKey } },
+      );
+      if (probe.ok) {
+        const meta = await probe.json();
+        if (meta && meta.platform && meta.platform !== platform) {
+          throw new Error(
+            `The Fiodos backend at ${apiUrl} does not support --platform ${platform} yet ` +
+            `(it would analyze as "${meta.platform}", missing the ${platform} platform spec). ` +
+            'Update/redeploy the backend and re-run the analysis.',
+          );
+        }
+      }
+    } catch (e) {
+      if (String(e && e.message).includes('does not support --platform')) throw e;
+      /* preflight is best-effort — the post-call echo guard still protects */
+    }
+  }
   const res = await fetch(`${apiUrl}/v1/developer/analyze`, {
     method: 'POST',
     headers: { 'Content-Type': 'application/json', 'x-api-key': apiKey },
@@ -351,6 +379,18 @@ async function analyzeViaProxy({ apiKey, apiUrl, model, user, task = 'analysis',
     throw new Error(`Hosted analysis failed: ${res.status} ${detail}`);
   }
   const data = await res.json();
+  // Platform degradation guard: an outdated backend that does not know the
+  // requested platform silently builds the generic WEB prompt instead — the
+  // manifest then LOOKS fine but misses the platform's spec (e.g. Shopify's
+  // declarative execution blocks, without which no commerce action can run).
+  // New backends echo the platform they actually used; a mismatch is fatal.
+  if (data.platform && platform && data.platform !== platform) {
+    throw new Error(
+      `The Fiodos backend at ${apiUrl} does not support --platform ${platform} yet ` +
+      `(it analyzed as "${data.platform}"). The manifest it would produce is missing ` +
+      `the ${platform} platform spec. Update/redeploy the backend and re-run the analysis.`,
+    );
+  }
   return {
     parsed: parseJsonContent(data.text || '{}'),
     usage: {

package/src/index.js

@@ -175,6 +175,11 @@ function logUser(line) {
   console.log(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
 }
 
+/** Human-readable pointer to the per-run change registry written in the repo. */
+function changeLogUserMessage(paths) {
+  return `We saved a summary of every file we changed — see ${paths.mdRel} (past runs in .fyodos/changes/)`;
+}
+
 /**
  * Ask the developer to confirm before the analysis runs. `yes` continues; any
  * other answer (or `no`) cancels instantly — the command ends without analyzing.
@@ -925,7 +930,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -973,7 +978,36 @@ async function main() {
     });
     logUser('Published to your project');
     if (orbWireResult && (orbWireResult.status === 'added' || orbWireResult.status === 'already')) {
-      logUser('Commit & push this theme repo — Shopify\u2019s GitHub sync deploys the orb to your live store.');
+      logUser('Commit & push this theme repo.');
+      // Shopify's GitHub sync only auto-updates the storefront when the
+      // CONNECTED theme is already the LIVE one. A brand-new theme connected
+      // from GitHub stays a draft until published ONCE by hand — every push
+      // after that keeps it live automatically. Without this line the orb can
+      // be fully wired and pushed and still never appear to real customers,
+      // with nothing in the CLI output explaining why.
+      logUser(
+        'If this is already your LIVE theme, that push alone puts the orb on your store. ' +
+        'If it\u2019s still a DRAFT (check the Shopify admin theme badge), publish it ONCE — ' +
+        'Online Store \u2192 Themes \u2192 \u22ef \u2192 Publish \u2014 then every future push stays live automatically.',
+      );
+      // New/trial Shopify stores are password-protected by default, and a
+      // password-protected storefront renders layout/password.liquid INSTEAD
+      // of layout/theme.liquid on every page — so without also wiring that
+      // layout (done above when the theme has one) the orb would be
+      // correctly installed and published yet invisible behind the password
+      // gate. Surfacing this explicitly since it is the #1 "installed
+      // correctly but nothing shows up" report on a fresh store.
+      if (orbWireResult.password) {
+        logUser(
+          orbWireResult.password.status === 'failed'
+            ? `Heads up: your store looks password-protected but the orb could not be added to ${orbWireResult.password.file} (${orbWireResult.password.reason}) — it will be invisible until you remove the password or fix that layout.`
+            : 'Your theme has a password page (layout/password.liquid) — the orb is embedded there too, so it still shows up while your store is password-protected.',
+        );
+      } else {
+        logUser(
+          'Heads up: if your store is still password-protected (common on new/trial stores) and your theme has NO separate layout/password.liquid, the orb won\u2019t show on the password page — remove the password (Online Store \u2192 Preferences) to test, or check under a real domain/plan.',
+        );
+      }
     }
 
     if (!noWire) {
@@ -985,7 +1019,7 @@ async function main() {
           orbResult: orbWireResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1108,7 +1142,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }
@@ -1187,7 +1221,7 @@ async function main() {
           envResult: envWriteResult,
         });
         const paths = writeChangeRegistry(analysisRoot, record);
-        logUser(`Change log: ${paths.mdRel} (history in .fyodos/changes/)`);
+        logUser(changeLogUserMessage(paths));
       } catch (e) {
         logDev(`[change-registry] could not write: ${e.message}`);
       }

package/src/postWireTest.js

@@ -127,6 +127,13 @@ function summarizeBuildOutput(raw, maxLines = 4) {
   return picked.slice(0, maxLines).join('\n').trim();
 }
 
+/** Does this output contain a signal that the CODE is broken (vs npm/env noise)? */
+function looksLikeCompileFailure(output) {
+  return /error\s+TS\d+|Type error:|Module not found|Can't resolve|Failed to compile|SyntaxError|Parsing error|Cannot find (?:module|name)/i.test(
+    String(output || ''),
+  );
+}
+
 async function runPostWireTest(appRoot, opts = {}) {
   const timeoutMs = opts.timeoutMs || 240000;
   if (!fs.existsSync(path.join(appRoot, 'node_modules'))) {
@@ -143,12 +150,26 @@ async function runPostWireTest(appRoot, opts = {}) {
     return { ok: true, stage: 'skipped-no-deps', command: '(none)', output: 'no build/typecheck script.' };
   }
 
-  const res = await runAsync('npm', chosen.args, {
-    cwd: appRoot,
-    timeout: timeoutMs,
-    env: { ...process.env, CI: '1', NODE_ENV: process.env.NODE_ENV || 'production' },
-    maxBuffer: 64 * 1024 * 1024,
-  });
+  const runOnce = () =>
+    runAsync('npm', chosen.args, {
+      cwd: appRoot,
+      timeout: timeoutMs,
+      env: { ...process.env, CI: '1', NODE_ENV: process.env.NODE_ENV || 'production' },
+      maxBuffer: 64 * 1024 * 1024,
+    });
+
+  let res = await runOnce();
+  // A spawn-level or npm-level failure with ZERO compile diagnostics is
+  // environment noise (npm cache contention, a concurrent process touching
+  // package.json, transient ENOENT), not broken code. Blaming the action for
+  // it drops perfectly good wiring, so retry once before judging.
+  const npmLevelFailure =
+    (res.error && res.error.code !== 'ETIMEDOUT') ||
+    (res.status !== 0 && res.status !== null && !looksLikeCompileFailure(`${res.stdout}\n${res.stderr}`));
+  if (npmLevelFailure) {
+    await new Promise((r) => setTimeout(r, 1500));
+    res = await runOnce();
+  }
 
   if (res.error && res.error.code === 'ETIMEDOUT') {
     return { ok: false, stage: 'timeout', command: chosen.label, output: `build exceeded ${Math.round(timeoutMs / 1000)}s` };

package/src/shopifyTheme.js

@@ -240,19 +240,16 @@ function escapeRe(s) {
 }
 
 /**
- * Inject (or refresh) the snippet in layout/theme.liquid, right before
+ * Inject (or refresh) the snippet into ONE liquid layout file, right before
  * </body>. Idempotent via the FYODOS:ORB markers: an existing block is
  * replaced in place, so re-running the CLI updates the snippet instead of
- * duplicating it. Returns { status: 'added'|'already'|'skipped'|'failed',
- * file, reason? }.
+ * duplicating it. Returns { status: 'added'|'already'|'skipped'|'failed'|
+ * 'not-found', file, reason?, refreshed? }.
  */
-function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
-  const relFile = path.join('layout', 'theme.liquid');
-  const file = path.join(appRoot, relFile);
+function injectSnippetInLayout(file, relFile, snippet, { noWire = false } = {}) {
   if (!fs.existsSync(file)) {
-    return { status: 'failed', file: relFile, reason: 'layout/theme.liquid not found' };
+    return { status: 'not-found', file: relFile };
   }
-  const snippet = buildShopifySnippet({ apiKey, apiUrl });
   const source = fs.readFileSync(file, 'utf8');
 
   const markerRe = new RegExp(`${escapeRe(ORB_START)}[\\s\\S]*?${escapeRe(ORB_END)}`);
@@ -273,6 +270,41 @@ function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
   return { status: 'added', file: relFile };
 }
 
+/**
+ * Wire the theme's layout(s). layout/theme.liquid is the one every storefront
+ * page uses and is REQUIRED. layout/password.liquid — when the theme ships
+ * one (Dawn, Horizon and most modern themes do) — is a SEPARATE layout Shopify
+ * renders INSTEAD of theme.liquid on every page while the store has password
+ * protection active (the default on every new/trial store, and very common on
+ * dev stores used to test an install). Without wiring it too, the orb is
+ * correctly embedded and published yet invisible to anyone hitting the
+ * password gate — "installed correctly but nothing shows up". Best-effort:
+ * its absence is normal (older/simpler themes have none) and never fails the
+ * install.
+ *
+ * Returns { status, file, reason?, refreshed?, password: {status, file,...} }
+ * — `password` mirrors the same shape for layout/password.liquid, or null
+ * when that file does not exist in this theme.
+ */
+function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
+  const snippet = buildShopifySnippet({ apiKey, apiUrl });
+
+  const themeRelFile = path.join('layout', 'theme.liquid');
+  const themeFile = path.join(appRoot, themeRelFile);
+  if (!fs.existsSync(themeFile)) {
+    return { status: 'failed', file: themeRelFile, reason: 'layout/theme.liquid not found', password: null };
+  }
+  const themeResult = injectSnippetInLayout(themeFile, themeRelFile, snippet, { noWire });
+
+  const passwordRelFile = path.join('layout', 'password.liquid');
+  const passwordFile = path.join(appRoot, passwordRelFile);
+  const passwordResult = fs.existsSync(passwordFile)
+    ? injectSnippetInLayout(passwordFile, passwordRelFile, snippet, { noWire })
+    : null;
+
+  return { ...themeResult, password: passwordResult };
+}
+
 function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
   const { blue = '', cyan = '', reset = '' } = colors;
   const say = (line) => console.error(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
@@ -285,6 +317,13 @@ function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
   } else if (!quiet) {
     say(`orb embed skipped (${result.reason || result.status})`);
   }
+
+  const pw = result.password;
+  if (pw && (pw.status === 'added' || pw.status === 'already')) {
+    say(`orb also embedded in ${pw.file} — keeps working while your store is password-protected`);
+  } else if (pw && pw.status === 'failed') {
+    say(`could not embed the orb in ${pw.file}: ${pw.reason} — the orb won't show while your store is password-protected`);
+  }
 }
 
 module.exports = {

package/src/verify.js

@@ -122,6 +122,79 @@ function sanitizeBubblePrompt(raw) {
   return s || undefined;
 }
 
+/** "es-ES" / "ES" → "es" (base language code, lowercased); undefined when unusable. */
+function sanitizeLanguageCode(raw) {
+  const code = String(raw || '').split(/[-_]/)[0].trim().toLowerCase();
+  return /^[a-z]{2,3}$/.test(code) ? code : undefined;
+}
+
+/**
+ * Sanitize a route's `bubblePrompts` translation map (fail-open, item never
+ * dropped): keeps only valid base-language keys whose values survive the same
+ * bubblePrompt hygiene. Returns undefined when nothing usable remains, so the
+ * SDK falls back to the single `bubblePrompt`.
+ */
+function sanitizeBubblePrompts(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const lang = sanitizeLanguageCode(key);
+    const prompt = sanitizeBubblePrompt(value);
+    if (lang && prompt && !(lang in out)) out[lang] = prompt;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Max length (chars) of a dashboard `labels` translation — it renders as a
+ * short UI label (route/action name), never a sentence.
+ */
+const MAX_LABEL = 60;
+
+/** Sanitize one dashboard label translation string (see sanitizeBubblePrompt). */
+function sanitizeLabelText(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_LABEL) s = s.slice(0, MAX_LABEL).trim();
+  return s || undefined;
+}
+
+/**
+ * Sanitize a route/action's `labels` translation map (fail-open, item never
+ * dropped): keeps only valid base-language keys whose values survive label
+ * hygiene. Returns undefined when nothing usable remains, so the dashboard
+ * falls back to the primary `label`. Unlike `bubblePrompts`, this map is
+ * REQUIRED by the analyzer prompt (es/en, unconditional) — but the CLI still
+ * never blocks a manifest over a missing/malformed translation.
+ */
+function sanitizeLabels(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined;
+  const out = {};
+  for (const [key, value] of Object.entries(raw)) {
+    const lang = sanitizeLanguageCode(key);
+    const label = sanitizeLabelText(value);
+    if (lang && label && !(lang in out)) out[lang] = label;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/**
+ * Sanitize the manifest-level `appLanguages` list (fail-open): dedupes and
+ * normalizes to base codes, preserving the model's order (primary first).
+ * Returns undefined when nothing usable remains (monolingual apps).
+ */
+function sanitizeAppLanguages(raw) {
+  if (!Array.isArray(raw)) return undefined;
+  const out = [];
+  for (const entry of raw) {
+    const lang = sanitizeLanguageCode(entry);
+    if (lang && !out.includes(lang)) out.push(lang);
+  }
+  return out.length > 0 ? out : undefined;
+}
+
 /** Normalize an expo-router href for comparison: strip (groups), trailing /index. */
 function normalizeHref(href) {
   return ('/' + String(href || '')
@@ -399,6 +472,15 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
     }
     if (bubble) route.bubblePrompt = bubble;
     else delete route.bubblePrompt;
+    // Multilingual bubble translations (fail-open): keep only clean entries so
+    // the orb can follow the app's active language; drop the map when empty.
+    const bubbles = sanitizeBubblePrompts(route.bubblePrompts);
+    if (bubbles) route.bubblePrompts = bubbles;
+    else delete route.bubblePrompts;
+    // Dashboard label translations (es/en) — see sanitizeLabels doc.
+    const routeLabels = sanitizeLabels(route.labels);
+    if (routeLabels) route.labels = routeLabels;
+    else delete route.labels;
   }
 
   // Schema coercion the model sometimes needs (same as the old engine).
@@ -414,10 +496,21 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
       action.confirmationMessageTemplate = `Confirm: ${action.label || action.intent}?`;
       provenance.notes.push(`action '${action.intent}': confirmation template filled mechanically`);
     }
+    // Dashboard label translations (es/en) — see sanitizeLabels doc.
+    const actionLabels = sanitizeLabels(action.labels);
+    if (actionLabels) action.labels = actionLabels;
+    else delete action.labels;
   }
 
+  // App-level supported languages (fail-open): normalized base codes, primary
+  // first; dropped entirely when the analysis found no i18n evidence.
+  const appLanguages = sanitizeAppLanguages(manifest.appLanguages);
+  const cleanManifest = { ...manifest, routes: dedupedRoutes, actions: dedupedActions };
+  if (appLanguages) cleanManifest.appLanguages = appLanguages;
+  else delete cleanManifest.appLanguages;
+
   return {
-    manifest: { ...manifest, routes: dedupedRoutes, actions: dedupedActions },
+    manifest: cleanManifest,
     provenance,
   };
 }

package/src/verifyWire.js

@@ -29,7 +29,14 @@ function normRel(p) {
 /** Extract "path(line,col): error" / "ERROR ... path:line" style lines. */
 function extractErrorLines(output) {
   const lines = String(output || '').split('\n');
-  return lines.filter((l) => /error\s+TS\d+|: error|ERROR\b|is not assignable|Cannot find|does not exist/i.test(l));
+  return lines.filter((l) => {
+    // npm's failure banner ("npm error path …", "npm ERR! command failed") is
+    // the WRAPPER around a failed script, not a diagnostic. Counting it as an
+    // error made an action fail with "compilation: npm error path <dir>" even
+    // when every real tsc line had been classified as style-only.
+    if (/^\s*npm\s+(error|ERR!)/i.test(l)) return false;
+    return /error\s+TS\d+|: error|ERROR\b|is not assignable|Cannot find|does not exist/i.test(l);
+  });
 }
 
 /**
@@ -52,8 +59,16 @@ function normErr(line) {
  * really broken), as opposed to a style violation? These mean the safety net
  * MUST act: the action does not actually work.
  */
+// "Declared but never used" (TS6133/6192/6196/6198/6199/6205) is a STRICTNESS
+// gate (noUnusedLocals), never broken code. It also appears as an ARTIFACT of
+// per-action isolated verification: wiring one bridge action alone leaves the
+// sibling symbols of the same destructuring temporarily unused, which used to
+// fail every action in that file (the navigate_section/logout production bug).
+const UNUSED_CODE_TS_RE = /error\s+TS6(?:133|192|196|198|199|205)\b/i;
+
 function isRealCompileError(line) {
   const l = String(line);
+  if (UNUSED_CODE_TS_RE.test(l)) return false;
   return /error\s+TS\d+|Type error:|Cannot find (?:module|name)|is not assignable|does not exist on type|has no exported member|Module not found|SyntaxError|Unexpected (?:token|keyword|reserved word)|Expression expected|Parsing error/i.test(l);
 }
 
@@ -66,6 +81,8 @@ function isRealCompileError(line) {
 function isLintError(line) {
   const l = String(line);
   if (isRealCompileError(l)) return false;
+  // Unused-symbol strictness (see UNUSED_CODE_TS_RE) is style, not brokenness.
+  if (UNUSED_CODE_TS_RE.test(l)) return true;
   // Reference to a known ESLint rule namespace / a bare `no-*` rule.
   if (/@typescript-eslint\/|react-hooks\/|jsx-a11y\/|@next\/next\/|\bimport\/[a-z-]+|\breact\/[a-z-]+|prettier\/|\bno-[a-z][a-z-]+\b/.test(l)) return true;
   // ESLint compact format "12:5  Error  message  rule" without a TS error code.

package/src/wireHandlers.js

@@ -98,6 +98,66 @@ function readFileSafe(appRoot, fileRel) {
   }
 }
 
+const SOURCE_EXTS = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.vue', '.svelte'];
+
+/** Read tsconfig/jsconfig path aliases once per appRoot: [{ prefix, target }]. */
+const aliasCache = new Map();
+function readPathAliases(appRoot) {
+  if (aliasCache.has(appRoot)) return aliasCache.get(appRoot);
+  const aliases = [];
+  for (const cfgName of ['tsconfig.json', 'tsconfig.app.json', 'jsconfig.json']) {
+    try {
+      const raw = fs.readFileSync(path.join(appRoot, cfgName), 'utf8');
+      // Tolerant parse: strip comments and trailing commas (tsconfig is JSONC).
+      const cfg = JSON.parse(raw.replace(/\/\*[\s\S]*?\*\/|\/\/[^\n]*/g, '').replace(/,\s*([}\]])/g, '$1'));
+      const co = cfg.compilerOptions || {};
+      const baseUrl = co.baseUrl || '.';
+      for (const [key, targets] of Object.entries(co.paths || {})) {
+        const target = Array.isArray(targets) ? targets[0] : targets;
+        if (!target) continue;
+        aliases.push({
+          prefix: key.replace(/\*$/, ''),
+          target: normRel(path.join(baseUrl, String(target).replace(/\*$/, ''))),
+        });
+      }
+    } catch {
+      /* no config or unparsable — skip */
+    }
+  }
+  aliasCache.set(appRoot, aliases);
+  return aliases;
+}
+
+/**
+ * Resolve an AI-proposed import path to a REAL file, tolerating what a human
+ * would write: tsconfig path aliases ('@/context/AppProvider') and
+ * extensionless specifiers. Returns the resolved app-relative path (with
+ * extension) or null. Rejecting these outright un-wired real actions whose
+ * only "fault" was that the AI wrote the import the way the codebase does.
+ */
+function resolveSourceFile(appRoot, fromRel) {
+  const candidates = [normRel(fromRel)];
+  for (const { prefix, target } of readPathAliases(appRoot)) {
+    const f = candidates[0];
+    if (f === prefix.replace(/\/$/, '') || f.startsWith(prefix)) {
+      candidates.push(normRel(target + f.slice(prefix.length)));
+    }
+  }
+  for (const rel of candidates) {
+    const abs = path.join(appRoot, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) return rel;
+    for (const ext of SOURCE_EXTS) {
+      if (fs.existsSync(`${abs}${ext}`)) return `${rel}${ext}`;
+    }
+    if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+      for (const ext of SOURCE_EXTS) {
+        if (fs.existsSync(path.join(abs, `index${ext}`))) return normRel(path.join(rel, `index${ext}`));
+      }
+    }
+  }
+  return null;
+}
+
 /** Count non-overlapping occurrences of a literal substring. */
 function countOccurrences(haystack, needle) {
   if (!needle) return 0;
@@ -112,14 +172,15 @@ function countOccurrences(haystack, needle) {
 
 // ── Mechanical verification (the safety net for AI-proposed wiring) ─────────────
 
-/** True if `symbol` appears as a standalone identifier somewhere in the file. */
+/** True if `symbol` appears as a standalone identifier somewhere in the file.
+ * The file path tolerates aliases/extensionless specifiers (resolveSourceFile). */
 function fileHasSymbol(appRoot, fileRel, symbol) {
   if (!fileRel || !symbol) return false;
-  const abs = path.join(appRoot, normRel(fileRel));
-  if (!fs.existsSync(abs)) return false;
+  const resolved = resolveSourceFile(appRoot, fileRel);
+  if (!resolved) return false;
   let content;
   try {
-    content = fs.readFileSync(abs, 'utf8');
+    content = fs.readFileSync(path.join(appRoot, resolved), 'utf8');
   } catch {
     return false;
   }
@@ -419,11 +480,12 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
   const importedNames = new Set();
   for (const imp of rawImports) {
     const name = String((imp && imp.name) || '').trim();
-    const from = normRel(imp && imp.from);
+    const rawFrom = normRel(imp && imp.from);
     const kind = (imp && imp.kind) || 'named';
-    if (!name || !from) return { reason: 'an import proposed by the AI is incomplete (missing name/from)' };
-    if (!fs.existsSync(path.join(appRoot, from))) {
-      return { reason: `the proposed import points to a non-existent file: '${from}'` };
+    if (!name || !rawFrom) return { reason: 'an import proposed by the AI is incomplete (missing name/from)' };
+    const from = resolveSourceFile(appRoot, rawFrom);
+    if (!from) {
+      return { reason: `the proposed import points to a non-existent file: '${rawFrom}'` };
     }
     // For named imports the symbol must be present in that file; default/namespace
     // bind the module's default/whole export so only file existence is checked.
@@ -514,6 +576,36 @@ function deriveBridgeAnchor(content, invoke) {
   return null;
 }
 
+/**
+ * "Once wired, never regressed": when the file ALREADY contains a generated
+ * block registering this intent (from a previous verified run), reuse that
+ * position instead of re-rolling the AI's anchor. Re-running the wiring is
+ * otherwise nondeterministic — a bad anchor + an unlucky AI correction can
+ * un-wire an action that worked yesterday. Returns the nearest line ABOVE the
+ * existing block that survives the strip and is unique in the stripped
+ * content (a deterministic anchor for the same spot), or null.
+ */
+function reuseExistingBlockAnchor(rawContent, strippedContent, intent) {
+  const blockRe = new RegExp(
+    `(${esc(EDIT_START_PREFIX)}[^\\n]*)\\n[\\s\\S]*?${esc(EDIT_END)}`,
+    'g',
+  );
+  let m;
+  while ((m = blockRe.exec(rawContent))) {
+    if (!GENERATED_HEADER_RE.test(m[1])) continue;
+    if (!new RegExp(`"${esc(intent)}"\\s*:`).test(m[0])) continue;
+    const lines = rawContent.slice(0, m.index).split('\n');
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i];
+      const t = line.trim();
+      if (!t || t.startsWith('//') || t.startsWith('/*') || t.startsWith('*')) continue;
+      if (line.includes('FYODOS:')) continue;
+      if (countOccurrences(strippedContent, line) === 1) return line;
+    }
+  }
+  return null;
+}
+
 /**
  * True when an anchor that appears several times is HARMLESS: every occurrence
  * resolves to the same actual insertion point (the nearest JSX `return`), so
@@ -554,9 +646,15 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const why = aiW.bridgeReason ? ` (${aiW.bridgeReason})` : '';
 
   if (!file) return { reason: `the AI marked a bridge but did not indicate the component file${why}` };
-  const content = readFileSafe(appRoot, file);
-  if (content == null) return { reason: `could not read the component '${file}' to apply the bridge` };
+  const rawContent = readFileSafe(appRoot, file);
+  if (rawContent == null) return { reason: `could not read the component '${file}' to apply the bridge` };
   if (!invoke) return { reason: `the AI did not provide the bridge 'invoke' expression for '${file}'` };
+  // Anchor decisions must be made on the content the block will ACTUALLY be
+  // inserted into: applyComponentEdits strips our previous blocks first. On a
+  // re-run over an already-wired file, the old generated block contains the
+  // same invoke expressions, so counting occurrences on the raw file falsely
+  // flags unique anchors as "ambiguous" and un-wires working actions.
+  const content = stripFiodosBlocks(rawContent);
 
   // Anchor resolution ladder: exact-unique AI anchor → harmless-ambiguous AI
   // anchor → mechanically derived declaration anchor → review. The old behavior
@@ -566,7 +664,13 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const occ = anchor ? countOccurrences(content, anchor) : 0;
   if (occ !== 1) {
     const scope = b.scope === 'class-field' ? 'class-field' : 'statement';
-    if (occ > 1 && scope === 'statement' && ambiguousAnchorSameInsertion(content, anchor)) {
+    const reused = reuseExistingBlockAnchor(rawContent, content, base.intent);
+    if (reused) {
+      // A previous run already wired this intent here and verified it; the
+      // proven position beats re-rolling an ambiguous AI anchor.
+      anchor = reused;
+      anchorDerived = true;
+    } else if (occ > 1 && scope === 'statement' && ambiguousAnchorSameInsertion(content, anchor)) {
       // Keep the AI anchor: every occurrence lands on the same insertion point.
     } else {
       const derived = deriveBridgeAnchor(content, invoke);
@@ -604,10 +708,18 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const importedNames = new Set();
   for (const imp of Array.isArray(b.imports) ? b.imports : []) {
     const name = String((imp && imp.name) || '').trim();
-    const from = normRel(imp && imp.from);
+    const rawFrom = normRel(imp && imp.from);
     const kind = (imp && imp.kind) || 'named';
-    if (!name || !from) return { reason: 'a bridge import is incomplete (missing name/from)' };
-    if (!fs.existsSync(path.join(appRoot, from))) return { reason: `the bridge import points to a non-existent file: '${from}'` };
+    if (!name || !rawFrom) return { reason: 'a bridge import is incomplete (missing name/from)' };
+    // The component often ALREADY imports the symbol (useApp, a store hook…).
+    // Re-importing it produces "Duplicate identifier" and fails the candidate,
+    // so an already-in-scope name is accepted without adding a second import.
+    if (new RegExp(`^\\s*import\\b[^;\\n]*[^\\w$]${esc(name)}[^\\w$][^;\\n]*from`, 'm').test(content)) {
+      importedNames.add(name);
+      continue;
+    }
+    const from = resolveSourceFile(appRoot, rawFrom);
+    if (!from) return { reason: `the bridge import points to a non-existent file: '${rawFrom}'` };
     if (kind === 'named' && !fileHasSymbol(appRoot, from, name)) return { reason: `named import '${name}' does not exist in '${from}'` };
     imports.push({ kind, name, importPath: relImport(path.dirname(file), from) });
     importedNames.add(name);
@@ -1195,10 +1307,31 @@ function buildHandlerDoc(plan, ctx = {}) {
 
 // ── Editing the user's own files (idempotent + reversible) ─────────────────────
 
-/** Remove any previously-inserted Fiodos blocks (idempotence across re-runs). */
+/**
+ * Header phrasings the CLI itself has ever written (current English + the
+ * localized parenthetical of older versions). Only blocks carrying one of
+ * these are OURS to strip.
+ */
+const GENERATED_HEADER_RE = /(generated by|auto-generado por|generado por)\s+Fiodos/i;
+
+/**
+ * Remove previously-inserted Fiodos blocks (idempotence across re-runs) —
+ * but ONLY the blocks this CLI generated. A developer can hand-write their
+ * own `FYODOS:BRIDGE` block (e.g. "manual wiring — logout") following our
+ * docs; that block is THEIR code and often the only user of an import
+ * (`useEffect`, a hook…). Stripping it orphans the import, the strict
+ * TypeScript check (noUnusedLocals) fails the candidate, and the whole
+ * wiring reverts — the exact failure that left navigate_section/logout
+ * unwired in production. Developer blocks are preserved verbatim.
+ */
 function stripFiodosBlocks(content) {
-  const re = new RegExp(`\\n?${esc(EDIT_START_PREFIX)}[^\\n]*[\\s\\S]*?${esc(EDIT_END)}\\n?`, 'g');
-  return content.replace(re, '\n');
+  const re = new RegExp(
+    `\\n?(${esc(EDIT_START_PREFIX)}[^\\n]*)[\\s\\S]*?${esc(EDIT_END)}\\n?`,
+    'g',
+  );
+  return content.replace(re, (block, headerLine) =>
+    GENERATED_HEADER_RE.test(headerLine) ? '\n' : block,
+  );
 }
 
 /** Insert an import block right after the file's last top-level import line. */
@@ -1261,6 +1394,26 @@ function insertRegisterBlock(content, file, anchor, block, scope) {
     return content.slice(0, endIdx) + '\n' + block + content.slice(endIdx);
   }
 
+  // When the anchor's own line is unmistakably a body STATEMENT (a declaration
+  // or a bare call ending in `;`), insert right AFTER it. Snapping to the
+  // nearest `return` instead can land the registration inside a conditional
+  // early-return branch (`if (authLoading) { … return <Spinner/> }`): it
+  // compiles, but in normal use that branch never runs and the bridge is never
+  // registered — the action silently dies at runtime.
+  const anchorLineStart = content.lastIndexOf('\n', at) + 1;
+  const anchorLineEnd = content.indexOf('\n', at);
+  const anchorLine = content.slice(anchorLineStart, anchorLineEnd === -1 ? content.length : anchorLineEnd).trim();
+  const isStatementLine =
+    /^(const|let|var)\b.*;\s*$/.test(anchorLine) || /^[\w$][\w$.]*\((?:[^()]|\([^()]*\))*\);\s*$/.test(anchorLine);
+  if (isStatementLine) {
+    // A multi-line declaration (`const { a, b } =\n  useApp();`) ends at the
+    // first `;` at/after the anchor, not at the anchor's own line end.
+    const semi = content.indexOf(';', at);
+    const stmtEnd = semi === -1 ? (anchorLineEnd === -1 ? content.length : anchorLineEnd) : content.indexOf('\n', semi);
+    const endIdx = stmtEnd === -1 ? content.length : stmtEnd;
+    return content.slice(0, endIdx) + '\n' + block + content.slice(endIdx);
+  }
+
   const ret = nearestJsxReturn(content, at);
   if (ret !== -1) {
     const lineStart = content.lastIndexOf('\n', ret) + 1;
@@ -1410,24 +1563,64 @@ function pickRelevantFiles(files, evidence, candidate, intent) {
     for (const imp of (candidate.bridge && candidate.bridge.imports) || []) if (imp && imp.from) wanted.add(normRel(imp.from));
     for (const r of candidate.requiredSymbols || []) if (r && r.file) wanted.add(normRel(r.file));
   }
+  // The most common unfixable failure is "symbol X is not available in the
+  // proposed file": the fix lives in ANOTHER component that consumes X. Give
+  // the corrector every file that mentions the invoked symbols (capped) so it
+  // can retarget the bridge instead of blindly retrying the same file.
+  const invokeSrc = String(
+    (candidate && ((candidate.bridge && candidate.bridge.invoke) || candidate.call)) || '',
+  );
+  const symbols = new Set();
+  let sm;
+  const symRe = /(?:^|[^.\w$])([A-Za-z_$][\w$]{2,})\s*\(/g;
+  while ((sm = symRe.exec(invokeSrc))) {
+    if (!JS_KEYWORDS.has(sm[1]) && !SAFE_GLOBALS.has(sm[1])) symbols.add(sm[1]);
+  }
+  if (symbols.size) {
+    let extra = 0;
+    for (const f of files) {
+      if (extra >= 4) break;
+      if (wanted.has(normRel(f.rel))) continue;
+      const content = String(f.content || '');
+      for (const sym of symbols) {
+        if (new RegExp(`(^|[^\\w$])${esc(sym)}([^\\w$]|$)`).test(content)) {
+          wanted.add(normRel(f.rel));
+          extra += 1;
+          break;
+        }
+      }
+    }
+  }
   const picked = files.filter((f) => wanted.has(normRel(f.rel)));
   return picked.length ? picked : files.slice(0, 4);
 }
 
-/** Write ONLY one entry (registry + bridge + its edit) for isolated verification. */
+/**
+ * Write ONLY one entry (registry + bridge + its edit) for isolated verification.
+ * Registry/bridge files from a PREVIOUS install are snapshotted and restored on
+ * revert instead of deleted: deleting them would break every OTHER file that
+ * still imports `../fyodos/bridge` from an earlier run, making all later
+ * verifications fail with a phantom "Cannot find module" (TS2307).
+ */
 function writeIsolated({ appRoot, fyodosDirAbs, entry, ts, esm, ext }) {
   const onePlan = { auto: [entry], review: [], manual: [], entries: [entry] };
   const registryAbs = path.join(fyodosDirAbs, `${REGISTRY_BASENAME}${ext}`);
   const bridgeAbs = path.join(fyodosDirAbs, `${BRIDGE_BASENAME}${ext}`);
-  const generated = [registryAbs];
+  const priorBackups = [];
+  const generated = [];
+  const snapshotOrCreate = (abs) => {
+    if (fs.existsSync(abs)) priorBackups.push({ file: abs, abs, original: fs.readFileSync(abs, 'utf8') });
+    else generated.push(abs);
+  };
+  snapshotOrCreate(registryAbs);
   if (entry.kind === 'bridge') {
+    snapshotOrCreate(bridgeAbs);
     fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
-    generated.push(bridgeAbs);
   }
   fs.writeFileSync(registryAbs, buildRegistryModule(onePlan, { ts, esm }));
   const edits = planComponentEdits(appRoot, onePlan, { ts });
   const { backups } = applyComponentEdits(appRoot, edits);
-  return { backups, generated, touched: [...edits.map((e) => e.file), registryAbs, bridgeAbs] };
+  return { backups: [...backups, ...priorBackups], generated, touched: [...edits.map((e) => e.file), registryAbs, bridgeAbs] };
 }
 
 /**

package/src/wireWeb.js

@@ -134,7 +134,7 @@ function agentSnippetVue() {
     `</script>\n\n` +
     `<template>\n` +
     `  <!-- ...your app... -->\n` +
-    `  <FiodosAgent :api-key="fyodosApiKey" :base-url="fyodosApiUrl" />\n` +
+    `  <FiodosAgent :api-key="fyodosApiKey" :base-url="fyodosApiUrl" locale-detection="document" />\n` +
     `</template>`
   );
 }
@@ -144,7 +144,7 @@ function agentSnippetSvelte() {
     `<script lang="ts">\n` +
     `  import FiodosAgent from '@fiodos/svelte/FiodosAgent.svelte';\n` +
     `</script>\n\n` +
-    `<FiodosAgent apiKey={import.meta.env.VITE_FYODOS_API_KEY} baseUrl={import.meta.env.VITE_FYODOS_API_URL} />`
+    `<FiodosAgent apiKey={import.meta.env.VITE_FYODOS_API_KEY} baseUrl={import.meta.env.VITE_FYODOS_API_URL} localeDetection="document" />`
   );
 }
 

package/src/wireWebMount.js

@@ -122,6 +122,10 @@ function buildEntryBootstrapBlock(opts = {}) {
     }
   }
   if (screenImportPath) lines.push(`  getCurrentRoute: ${SCREEN_ROUTE_EXPORT},`);
+  // Language link (never left disconnected): the orb follows the page's live
+  // <html lang>, so analyzer bubble translations track the app's language
+  // switcher automatically.
+  lines.push("  localeDetection: 'document',");
   lines.push('  mount: true,');
   lines.push('});');
   lines.push(ORB_SCRIPT_END);
@@ -243,6 +247,10 @@ function agentJsx(framework, ts, indent = '  ') {
     `${indent}<FiodosAgent\n` +
     `${indent}  apiKey={${keyExpr}}\n` +
     `${indent}  apiUrl={${urlExpr}}\n` +
+    // Language link (never left disconnected): the orb follows the page's live
+    // <html lang>, so analyzer bubble translations track the app's language
+    // switcher automatically.
+    `${indent}  localeDetection="document"\n` +
     `${indent}/>`
   );
 }
@@ -644,7 +652,7 @@ function injectVueSfc(plan) {
   }
   const block = [
     ORB_HTML_START,
-    '  <FiodosAgent :api-key="fyodosApiKey" :base-url="fyodosApiUrl" />',
+    '  <FiodosAgent :api-key="fyodosApiKey" :base-url="fyodosApiUrl" locale-detection="document" />',
     ORB_HTML_END,
   ].join('\n');
   source = source.replace('</template>', `${block}\n</template>`);
@@ -662,7 +670,7 @@ function injectSvelteSfc(plan) {
   }
   const block = [
     ORB_HTML_START,
-    '<FiodosAgent apiKey={import.meta.env.VITE_FYODOS_API_KEY} baseUrl={import.meta.env.VITE_FYODOS_API_URL} />',
+    '<FiodosAgent apiKey={import.meta.env.VITE_FYODOS_API_KEY} baseUrl={import.meta.env.VITE_FYODOS_API_URL} localeDetection="document" />',
     ORB_HTML_END,
   ].join('\n');
   if (source.includes('</main>')) {
@@ -699,7 +707,7 @@ function injectAngularComponent(plan) {
     );
   }
 
-  const block = [ORB_HTML_START, '<fyodos-agent [apiKey]="fyodosApiKey" [baseUrl]="fyodosApiUrl" />', ORB_HTML_END].join('\n');
+  const block = [ORB_HTML_START, '<fyodos-agent [apiKey]="fyodosApiKey" [baseUrl]="fyodosApiUrl" localeDetection="document" />', ORB_HTML_END].join('\n');
   html = `${html.trimEnd()}\n${block}\n`;
   writeFile(target.file, ts);
   writeFile(templatePath, html);