@fiodos/cli 0.1.28 → 0.1.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/cli",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "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/collect.js

@@ -80,14 +80,27 @@ function tierFor(rel, platform) {
     if (/^sections\//.test(p)) return 2;
     return 3; // snippets/, config/ (settings_data.json can be huge), rest
   }
+  return tierForApp(p);
+}
+
+function tierForApp(p) {
   if (/^(src\/)?app\//.test(p)) return 0; // expo-router / Next screens
-  if (/(^|\/)(screens?|pages?|views?|routes?|activities|fragments)\//i.test(p)) return 0;
-  if (/(screen|page|view|activity|fragment)\.(dart|kt|swift)$/i.test(p)) return 0;
+  // `sections/` and `panels/` are SCREEN BODIES in shell-based apps (a Shell
+  // page switches between section components): they carry the visible controls
+  // (color pickers, toggles) the analyzer must read to emit their actions.
+  // Ranking them as generic components (tier 3) silently dropped them under
+  // budget pressure and whole screens became invisible to the AI.
+  if (/(^|\/)(screens?|pages?|views?|routes?|sections?|panels?|activities|fragments)\//i.test(p)) return 0;
+  if (/(screen|page|view|activity|fragment|section)\.(dart|kt|swift)$/i.test(p)) return 0;
+  // Central state gets its OWN tier right after screens: the providers/stores
+  // define the setters that make screen controls wire-able actions. Sharing a
+  // tier with the (numerous) service/lib files let alphabetical fill starve
+  // out AppProvider-style files, and the AI had to guess every handler name.
   if (/(^|\/)(state|store|stores|context|contexts|redux|providers?|blocs?|cubits?|viewmodels?)\//i.test(p)) return 1;
   if (/(viewmodel|notifier|bloc|cubit|store|controller)\.(dart|kt|swift)$/i.test(p)) return 1;
-  if (/(^|\/)(services?|api|db|data|domain|agent|handlers?|actions?|lib|utils|repositories|repository|usecases?)\//i.test(p)) return 1;
-  if (/(^|\/)(hooks)\//.test(p)) return 2;
-  return 3; // generic components / ui
+  if (/(^|\/)(services?|api|db|data|domain|agent|handlers?|actions?|lib|utils|repositories|repository|usecases?)\//i.test(p)) return 2;
+  if (/(^|\/)(hooks)\//.test(p)) return 3;
+  return 4; // generic components / ui
 }
 
 function collectFiles(appRoot, { maxInputTokens = 150_000, platform = 'mobile' } = {}) {
@@ -108,7 +121,21 @@ function collectFiles(appRoot, { maxInputTokens = 150_000, platform = 'mobile' }
       if (!codeExt.has(path.extname(entry.name))) continue;
       if (SKIP_FILES.test(rel)) continue;
       if (isNative && SKIP_NATIVE_FILES.test(rel)) continue;
-      const content = fs.readFileSync(full, 'utf8');
+      let content = fs.readFileSync(full, 'utf8');
+      if (platform === 'shopify' && /^locales\//.test(rel.replace(/\\/g, '/'))) {
+        // Theme-editor translations (merchant-facing settings strings), not
+        // storefront language evidence — pure noise for the analysis.
+        if (/\.schema\.json$/.test(rel)) continue;
+        // Non-default storefront locales: what matters is THAT the language is
+        // published (the filename carries the code) — that is the evidence the
+        // MULTILINGUAL rule needs to emit appLanguages/bubblePrompts. Sending
+        // each file whole (tens of KB × dozens of locales) blew the budget and
+        // the alphabetical cut dropped exactly the important ones (en/es
+        // arrived after bg/cs/da…), so the AI saw a "monolingual" store.
+        if (!/\.default\.json$/.test(rel)) {
+          content = '{"__fyodos_note": "published storefront locale (content elided; this language IS offered to shoppers — count it in appLanguages/bubblePrompts)"}';
+        }
+      }
       files.push({ rel, content, tier: tierFor(rel, platform), chars: content.length });
     }
   };
@@ -118,10 +145,48 @@ function collectFiles(appRoot, { maxInputTokens = 150_000, platform = 'mobile' }
   files.sort((a, b) => a.tier - b.tier || a.rel.localeCompare(b.rel));
 
   const budgetChars = maxInputTokens * CHARS_PER_TOKEN;
+
+  // Floor-reserved fill. A pure greedy fill let a fat tier 0 (many large
+  // screen files) consume the WHOLE budget and push out tier 1 entirely —
+  // i.e. the app's central state/providers (AppProvider, stores) vanished
+  // from the analysis, so the AI could not see the setters that make
+  // configuration controls real actions and had to guess every handler name.
+  // Each lower tier gets a guaranteed FLOOR (share of the total budget,
+  // capped at its real demand); screens still get everything left over, and a
+  // final backfill hands unused room to deferred files in tier order.
+  const FLOOR_SHARE = { 1: 0.2, 2: 0.05, 3: 0.02, 4: 0.02 };
+  const demand = new Map();
+  for (const f of files) demand.set(f.tier, (demand.get(f.tier) ?? 0) + f.chars);
+
   const included = [];
-  const omitted = [];
+  const deferred = [];
   let used = 0;
-  for (const f of files) {
+  const tiers = [...demand.keys()].sort((a, b) => a - b);
+  for (const tier of tiers) {
+    // Reserve, for every LOWER-priority tier that still has files, the smaller
+    // of its floor and what it actually needs.
+    let reserved = 0;
+    for (const t of tiers) {
+      if (t <= tier) continue;
+      reserved += Math.min((FLOOR_SHARE[t] ?? 0) * budgetChars, demand.get(t));
+    }
+    const available = budgetChars - used - reserved;
+    let tierUsed = 0;
+    for (const f of files) {
+      if (f.tier !== tier) continue;
+      if (tierUsed + f.chars <= available) {
+        included.push(f);
+        tierUsed += f.chars;
+      } else {
+        deferred.push(f);
+      }
+    }
+    used += tierUsed;
+  }
+  // Backfill: any room the floors did not consume goes back to the deferred
+  // files, highest tier priority first.
+  const omitted = [];
+  for (const f of deferred) {
     if (used + f.chars <= budgetChars) {
       included.push(f);
       used += f.chars;
@@ -129,6 +194,8 @@ function collectFiles(appRoot, { maxInputTokens = 150_000, platform = 'mobile' }
       omitted.push({ rel: f.rel, chars: f.chars, tier: f.tier });
     }
   }
+  // Restore deterministic tier/path order after the backfill.
+  included.sort((a, b) => a.tier - b.tier || a.rel.localeCompare(b.rel));
 
   return {
     included,

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);
+  });
 }
 
 /**

package/src/wireHandlers.js

@@ -576,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
@@ -634,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);
@@ -675,6 +711,13 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
     const rawFrom = normRel(imp && imp.from);
     const kind = (imp && imp.kind) || 'named';
     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}'` };
@@ -1291,9 +1334,14 @@ function stripFiodosBlocks(content) {
   );
 }
 
-/** Insert an import block right after the file's last top-level import line. */
+/** Insert an import block right after the file's last top-level import statement.
+ *  Matches the WHOLE statement through its module string — a per-line regex put
+ *  the block INSIDE multi-line imports (`import {\n  a,\n} from 'x';`), corrupting
+ *  the file (TS1003 "Identifier expected") and failing the wiring of every action
+ *  in that file. `[^'"]*` cannot skip a quote, so the match always stops at the
+ *  first quoted module specifier, then runs to that line's end. */
 function insertImportBlock(content, importBlock) {
-  const importLineRe = /^[ \t]*import\b[^\n]*\n/gm;
+  const importLineRe = /^[ \t]*import\b[^'"]*['"][^'"]+['"][^\n]*\n/gm;
   let lastEnd = -1;
   let m;
   while ((m = importLineRe.exec(content))) lastEnd = m.index + m[0].length;
@@ -1351,6 +1399,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;
@@ -1500,6 +1568,34 @@ 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);
 }

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);